一、swagger简介
swagger是一个可以编写接口的API文档并且可以调试接口的一个工具，从swagger的官网上可以看到主要有swagger-editor、swagger-ui以及swagger-codegen三个工具。swagger-editor用来编辑swagger格式的文档，swagger-ui用来展示swagger格式的文档而swagger-codegen则可以根据文档来生成不同开发语言的客户端。同时还有个swagger hub则是集成了以上三种工具的一个交由swagger托管的一个网站。
二、swagger-editor
从官网上可以看到，我们可以自行搭建swagger-editor环境，由于swagger已经发布了docker镜像，因此我们只要使用docker运行镜像即可。
我访问下10030端口，即可以看到swagger-editor的页面，如下
三、swagger-ui
swagger-editor编辑后的swagger接口文档需要使用swagger-ui来查看，swagger-ui在官网上也可以找到运行方式，也是做成了docker镜像。
访问虚拟机80端口，就可以访问到swagger-ui界面了
但是有问题，就是swagger.json如何才能变成自己有swagger-editor编写的文档呢，使用了官网的方法好像都无法修改上面的swagger内容，看了下swagger-ui在github上面的用于构建镜像的Dockerfile文件，如下
使用了nginx，因此我们需要把自己编辑好的swagger.json放入到和swagger-ui页面相同的目录下，这样我们就可以访问自己的swagger.json了。
进入到容器里面查看，可以看到我们自己的swagger.json，我们可以访问下
可以看到我们可以访问自己的swagger文档了
四、如果文档不需要存磁盘，我们可以使用代码来生成API文档
1.需要引入的swagger依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
2.swagger配置
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerAutoConfiguration {
@Bean
public Docket customImplementation() {
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("API 文档")
.description("")
.version("1.0")
.build();
}
}
3.需要生成接口文档的controller类和方法上添加@Api和@ApiOperation注解即可
参考文章
1.swagger2的常用注解，传递参数的注意使用方法
https://www.cnblogs.com/fengli9998/p/7921601.html
2.使用自定义注解生成文档
https://blog.csdn.net/s332755645/article/details/80405972
3.docker部署swagger
https://blog.csdn.net/sweetyoyy/article/details/78388524?foxhandler=RssReadRenderProcessHandler