是时候换种方式使用Swagger了

是时候换种方式使用Swagger了

为啥用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

已经可以看到生成的最原始的文档。

Swagger-1.png

进阶使用

注解天下第一

名称	作用
@OpenAPIDefinition	定义例如文档名称介绍等
@Tag	用来定义一组接口的名称以及说明
@Operation	定义具体接口操作
@ApiResponse	定义返回状态
@Parameter	定义参数信息
@Schema	用于定义返回对象或者字段

更多注解可参考附录[^6]

下图是最终效果

Swagger-1.png

下载Github项目示例

总结

相比Springfox我更推荐大家使用Springdoc, 目前Springdoc版本更新社区也更活跃, 项目使用也更简单方便。

希望大家都可以输出好文档！

附录

[1] Swagger IO
https://swagger.io/
[2] Springdoc
https://springdoc.org/
[3] OpenAPI-Specification
https://github.com/OAI/OpenAPI-Specification
[4] Springfox
https://github.com/springfox/springfox
[5] Swagger Core 2.X
https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Getting-started
[6] Swagger 2.X Annotations
https://github.com/swagger-api/swagger-core/wiki/Swagger-2.X---Annotations