使用springdoc搭建api文档管理服务
1. Springdoc-openapi Modules
更多详情参考:Springdoc-openapi Modules
2. pom引入
- 如果使用Spring-webmvc,本文以Spring-webmvc为例展开。
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.5.9</version>
</dependency>
- 如果使用Spring-webflux
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webflux-ui</artifactId>
<version>1.5.9</version>
</dependency>
3. 配置文件
springdoc:
version: '@springdoc.version@'
swagger-ui:
display-request-duration: true
operationsSorter: method
disable-swagger-default-url: true
use-root-path: false
如果springdoc.swagger-ui.use-root-path = true,则访问应用的根目录既可以打开swagger-ui的首页,如 http://localhost:8080;
如果配置了springdoc.swagger-ui.path,如(springdoc.swagger-ui.path = /swagger-ui),则需要访问 http://localhost:8080/swagger-ui访问swagger首页。
4. Swagger Configuration
4.1 How to configure
Swagger UI accepts configuration parameters in four locations.
From lowest to highest precedence:
- The swagger-config.yaml in the project root directory, if it exists, is baked into the application
- configuration object passed as an argument to Swagger UI (SwaggerUI({ … }))
- configuration document fetched from a specified configUrl
- configuration items passed as key/value pairs in the URL query string
更多配置信息参考:Swagger UI Configuration
5. Swagger UI 加载流程
5.1 access swagger ui path
- controller
- build redirect url, set response location and return.
5.2 redirect to swagger config url
5.3 access api docs url
参考
Springdoc-openapi Modules
OpenAPI Specification
Swagger UI Configuration