什么是Swagger
Swagger是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。它可以轻松的整合到现有的项目中,生成文档提供给前端开发人员来调用,还可以做功能测试。
在 Spring Boot 中,我们可以通过集成 Swagger 来实现接口文档的自动生成。Swagger 通过注解来描述接口,然后根据这些注解自动生成接口文档。
什么是Springdoc-openapi
SpringBoot官宣推出API工具
官网地址 https://springdoc.org/#getting-started
支持Spring WebFlux项目,甚至Spring Rest和Spring Native项目
什么是openapi
OpenAPI Specification(OAS)定义了一个标准,用于描述REST API。它具有与Swagger 2.0规范兼容的根基础,但具有更强大的功能,例如支持JSON和YAML序列化,更好的安全性等。
[了解OpenAPI:什么是OpenAPI及其作用] https://zhuanlan.zhihu.com/p/624773325
Springdoc-openapi 与 Swagger的区别
Springdoc-openapi是SpringBoot官方推出的API工具,支持Spring WebFlux项目,甚至Spring Rest和Spring Native项目。
Springdoc-openapi是基于OpenAPI 3规范构建的,而Swagger是基于OpenAPI 2规范构建的。
Springdoc-openapi 能代替 Swagger么
答案是可以的,但是Springdoc-openapi是基于OpenAPI 3规范构建的,而Swagger是基于OpenAPI 2规范构建的,所以在使用Springdoc-openapi时,需要注意一些细节,比如注解的变化等。
Springdoc-openapi的使用
引入依赖
1 | <dependency> |
1 | # swagger-ui custom path |
启动项目
访问 http://localhost:8080/swagger-ui.html
访问 http://localhost:8080/v3/api-docs 可以查看接口文档的json数据,该文档可以导出到支持OAS3.0的工具中,比如apifox
注意事项
注解
Springdoc-openapi中的注解与Swagger中的注解不同,细微之处可能有些调整
拦截器
如果有拦截器 注意查看是否拦截了swagger的请求
https://app.apifox.com/
可以使用apifox 导入swagger的json数据,然后进行接口测试,并且可以导出更友好的接口文档