共计 1707 个字符，预计需要花费 5 分钟才能阅读完成。
Open API 是一个标准，它的主要作用是描述 REST API，既可以作为文档给开发者阅读，又可以让机器根据这个文档自动生成客户端代码等。
在 Spring Boot 应用中，假设我们编写了一堆 REST API，如何添加 Open API 的支持？
我们只需要在 pom.xml 中加入以下依赖：
- org.springdoc:springdoc-openapi-starter-webmvc-ui:2.0.0
然后呢？没有然后了，直接启动应用，打开浏览器输入http://localhost:8080/swagger-ui.html：
立刻可以看到自动生成的 API 文档，这里列出了 3 个 API，来自 api-controller（因为定义在ApiController 这个类中），点击某个 API 还可以交互，即输入 API 参数，点“Try it out”按钮，获得运行结果。
是不是太方便了！
因为我们引入 springdoc-openapi-ui 这个依赖后，它自动引入 Swagger UI 用来创建 API 文档。可以给 API 加入一些描述信息，例如：
@RestController
@RequestMapping("/api")
public class ApiController {
...
@Operation(summary = "Get specific user object by it's id.")
@GetMapping("/users/{id}")
public User user(@Parameter(description = "id of the user.") @PathVariable("id") long id) {return userService.getUserById(id);
}
...
}
@Operation可以对 API 进行描述，@Parameter可以对参数进行描述，它们的目的是用于生成 API 文档的描述信息。添加了描述的 API 文档如下：
大多数情况下，不需要任何配置，我们就直接得到了一个运行时动态生成的可交互的 API 文档，该 API 文档总是和代码保持同步，大大简化了文档的编写工作。
要自定义文档的样式、控制某些 API 显示等，请参考 springdoc 文档。
配置反向代理
如果在服务器上，用户访问的域名是 https://example.com，但内部是通过类似 Nginx 这样的反向代理访问实际的 Spring Boot 应用，比如http://localhost:8080，这个时候，在页面https://example.com/swagger-ui.html 上，显示的 URL 仍然是http://localhost:8080，这样一来，就无法直接在页面执行 API，非常不方便。
这是因为 Spring Boot 内置的 Tomcat 默认获取的服务器名称是 localhost，端口是实际监听端口，而不是对外暴露的域名和80 或443端口。要让 Tomcat 获取到对外暴露的域名等信息，必须在 Nginx 配置中传入必要的 HTTP Header，常用的配置如下：
# Nginx 配置
server {
...
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}
...
}
然后，在 Spring Boot 的 application.yml 中，加入如下配置：
server:
# 实际监听端口:
port: 8080
# 从反向代理读取相关的 HTTP Header:
forward-headers-strategy: native
重启 Spring Boot 应用，即可在 Swagger 中显示正确的 URL。
练习
利用 springdoc 实现 API 文档。
下载练习
小结
使用 springdoc 让其自动创建 API 文档非常容易，引入依赖后无需任何配置即可访问交互式 API 文档。
可以对 API 添加注解以便生成更详细的描述。
