SpringBoot整合Swagger3生成接口文档
一、Swagger简介
Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，后来成为了 Open API 标准的主要定义者。Swagger 提供了一套通过代码和注解自动生成文档的方法，对于保证API 文档的及时性将有很大的帮助。
Swagger2：17年停止维护
Swagger3（Open Api3）：17年发布
Swagger官网提供的开源工具：
Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。
Swagger UI:提供了一个可视化的UI页面展示描述文件。对相关接口进行查阅和做一些简单的接口请求。支持在线导入描述文件和本地部署UI项目
Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。
Swagger Inspector: 和postman有些相似，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。
Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。
Spring提供的Springfox Swagger：
可以将基于SpringMVC和Spring Boot项目的项目代码，自动生成JSON格式的描述文件
二、SpringBoot整合Swagger3步骤：
1.pom.xml文件中引入Swagger3依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
2.编写Swagger3Config配置类
package com.example.swaggerDemo.util;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
* @Author 小舟同学
* @Date 2021/4/26 17:35
* @Description 说明：Swagger3Config的配置
*/
//@EnableSwagger2 是 swagger2.0版本的注解
//swagger在3.0之后换成了@EnableOpenApi
@Configuration
@EnableOpenApi//开启Swagger3
public class Swagger3Config {
@Bean
public Docket createRestApi(){
//swagger设置，基本信息，要解析的接口及路径等
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))//设置扫描路径 //设置通过什么方式定位需要自动生成文档的接口，这里定位方法上的@ApiOperation注解
.paths(PathSelectors.any())接口URI路径设置，any是全路径，也可以通过PathSelectors.regex()正则匹配
.build();
}
//生成接口信息，包括标题、联系人，联系方式等
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("适用于前后端分离统一的接口文档")
.version("1.0")
.build();
}
}
3.Swagger注解的使用说明
@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看不到，所以不需要配置"
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· div（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性
4.Controller层的配置(Swagger3注解使用位置举例）
package com.example.swaggerDemo.controller;
import com.example.swaggerDemo.bean.JsonBean;
import com.example.swaggerDemo.service.IyunhuService;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @Author 小舟同学
* @Date 2021/4/23 13:57
* @Description 说明：测试Swagger注解使用
*/
@Api(tags = "测试接口文档类")
@RestController
@RequestMapping("/test")
public class TestController {
private static final Logger logger = LoggerFactory.getLogger(TestController.class);
@Autowired
IyunhuService service;
@ApiOperation("转账")
@PostMapping("/transfer")
public Object transfer(JsonBean json) throws Exception{
return service.transfer(json);
};
@ApiOperation("转账查询")
@ApiImplicitParams({
@ApiImplicitParam(name = "payexacctno", value = "企业账号", dataType = "String", required = true),
@ApiImplicitParam(name = "payexacctname", value = "企业户名", dataType = "String", required = true),
@ApiImplicitParam(name = "orderid", value = "订单号", dataType = "String", required = true),
})
@PostMapping("/transferQuery")
public Object transferQuery(JsonBean json) throws Exception{
return service.transferQuery(json);
};
}
5.启动项目打开默认地址：
http://localhost:8080/swagger-ui/index.html
注意： (swagger2.xx版本访问的地址为：http://localhost:8080/swagger-ui.html)
6.在线测试
（1）点击Try it out 然后填写参数
（2）填写好后执行测试
（3）以下出测试结果
关于swagger3.0 与2.xx配置差异可以查看该文：
https://blog.csdn.net/weixin_44203158/article/details/109137799.
编写不易，如果有帮助到的话，可以关注，点赞和收藏哦~ ↩︎
转载：https://blog.csdn.net/qq_44021875/article/details/116199409
查看评论