是时候换种方式使用Swagger了

2020-02-14 本文已影响0人 Anricx

为啥用Swagger

懒! 年前的时候已写一份优秀的文档为己任。当反复切换文档编写工具, 你会发现还是编写代码的时候直接写好注释然后能自动生成文档是一件多爽的事情。而Swagger正式为此而生！

搜索SpringBoot加入Swagger, 千篇一律都是让你引入依赖:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

然后配置SwaggerConfig类, 定义Docket等等...

所以大部分人接入Swagger都是采用都这个方式, 但是这个库太过时了！

这个库最新版本还停留在2018年6月, Swagger 2.x都发布快两年了, 这个库目前还不支持2.0，虽然作者在2019年8月发布帖子说明了当前都进度(点击查看), 但是截止2020年1月目前依然没有看到任何会完成支持的希望！

那为什么我那么在意Swagger 2.x? 是因为2.0实现标准是OpenAPI 3.0, 具体是什么可参考附录[3], 总之更好更强！

所以我放弃了，是时候换条路子了。

Springdoc也是一个为spring项目自动生成API文档的工具。

Maven项目添加依赖, 项目版本可自行在仓库选择最新版本。

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.2.30</version>
</dependency>

记住然后你什么都不用做, 直接访问

http://127.0.0.1:8080/swagger-ui.html

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

Swagger-1.png

注解天下第一

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

下图是最终效果

Swagger-1.png

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

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