为啥用Swagger
懒!
年轻的时候已写一份优秀的文档为己任。当反复切换文档编写工具, 你会发现还是编写代码的时候直接写好注释然后能自动生成文档是一件多爽的事情。而Swagger正式为此而生!
以前怎么用Swagger
搜索SpringBoot加入Swagger, 千篇一律都是让你引入依赖:
io.springfox springfox-swagger2 2.9.2
然后配置SwaggerConfig类, 定义Docket等等…
所以大部分人接入Swagger都是采用都这个方式, 但是这个库太过时了!
这个库最新版本还停留在2018年6月, Swagger 2.x都发布快两年了, 这个库目前还不支持2.0,虽然作者在2019年8月发布帖子说明了当前都进度, 但是截止2020年1月目前依然没有看到任何会完成支持的希望!
那为什么我那么在意Swagger 2.x? 是因为2.0实现标准是OpenAPI 3.0, 具体是什么可参考附录[3], 总之更好更强!
所以我放弃了,是时候换条路子了。
发现新大陆 - Springdoc
Springdoc也是一个为spring项目自动生成API文档的工具。
有什么特性
- 实现OpenAPI 3规范 - 当然由于它直接基于Swagger 2.x
- SpringBoot 1.x/2.x - 新老都完美支持
- JSR-303标准 - 接口对象都定义更加规范通用
- Swagger UI - 比较好看了
- OAuth2 - 可能用不着
如何使用
Maven项目添加依赖, 项目版本可自行在仓库选择最新版本。
org.springdoc springdoc-openapi-ui 1.2.30
记住然后你什么都不用做, 直接访问
http://127.0.0.1:8080/swagger-ui.html
已经可以看到生成的最原始的文档。
进阶使用
注解天下第一
更多注解可参考附录[^6]
下图是最终效果
下载项目示例私信
总结
相比Springfox我更推荐大家使用Springdoc, 目前Springdoc版本更新社区也更活跃, 项目使用也更简单方便。
希望大家都可以输出好文档!
附录
[1] Swagger IO
[2] Springdoc
[3] OpenAPI-Specification
[4] Springfox
[5] Swagger Core 2.X
[6] Swagger 2.X Annotations