提示：文章写完后，目录可以自动生成，如何生成可参考右边的帮助文档

---

Swagger

一、简介

官网：https://swagger.io/

• Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
• Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger消除了调用服务时可能会有的猜测。

Swagger 的优势

• 支持 API 自动生成同步的在线文档：使用 Swagger后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供 Web 页面在线测试 API：光有文档还不够，Swagger生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

二、基本使用

1. 导入相关依赖

通过在项目中引入 Springfox，可以扫描相关的代码，生成该描述文件，进而生成与代码一致的接口文档和客户端代码。

        <!-- swagger --><dependency><groupId>io.springfox</groupId><artifactId>springfox-spring-web</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>

2. 编写配置文件

在配置文件 config 目录下，添加 swagger 的配置文件 SwaggerConfig.java

@Configuration // 配置类
@EnableSwagger2 // 开启 swagger2 的自动配置
public class SwaggerConfig {
}

可以看到 Swagger 文档中大概有这四类信息

• 组
• 基本信息
• 接口信息
• 实体类信息

2.1 配置基本信息

SwaggerConfig.java 配置文件添加以下内容：

    @Beanpublic Docket docket() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)// 配置基本信息.apiInfo(apiInfo());}// 基本信息设置private ApiInfo apiInfo() {Contact contact = new Contact("米大傻", // 作者姓名"https://blog.csdn.net/xhmico?type=blog", // 作者网址"777777777@163.com"); // 作者邮箱return new ApiInfoBuilder().title("多加辣-接口文档") // 标题.description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述.termsOfServiceUrl("https://www.baidu.com") // 跳转连接.version("1.0") // 版本.license("Swagger-的使用(详细教程)").licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535").contact(contact).build();}

2.2 配置接口信息

    @Beanpublic Docket docket() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2)// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors//.any() // 扫描全部的接口，默认//.none() // 全部不扫描.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用//.withClassAnnotation(RestController.class) // 扫描带有指定注解的类下所有接口//.withMethodAnnotation(PostMapping.class) // 扫描带有只当注解的方法接口).paths(PathSelectors.any() // 满足条件的路径，该断言总为true//.none() // 不满足条件的路径，该断言总为false（可用于生成环境屏蔽 swagger）//.ant("/user/**") // 满足字符串表达式路径//.regex("") // 符合正则的路径).build();}

2.3 配置分组信息

    /*** 展示 controller 包下所有的接口*/@Beanpublic Docket docket1() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2).groupName("mike") // 修改组名为 "mike"// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用).paths(PathSelectors.any() // 满足条件的路径，该断言总为true).build();}/*** 展示路径为 /error 的所有接口（基础接口）*/@Beanpublic Docket docket2() {// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2).groupName("yank") // 修改组名为 "yank"// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors.any() // 扫描全部的接口，默认).paths(PathSelectors.ant("/error") // 满足字符串表达式路径).build();}

3. 控制 Swagger 的开启

application.yml 内容如下，用于指定选择的环境：

spring:profiles:active: dev

可以通过代码判断此时是在什么环境：dev、test、pro，如果是在 pro 生产环境，则关闭 swagger。

    /*** swagger 配置* @param environment 环境*/@Beanpublic Docket docket(Environment environment) {// 设置环境范围Profiles profiles = Profiles.of("dev","test");// 如果在该环境返回内则返回：true，反之返回 falseboolean flag = environment.acceptsProfiles(profiles);// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2).enable(flag) // 是否开启 swagger：true -> 开启，false -> 关闭;}

4. 常用注解使用

@ApiModel

@ApiModelProperty

@ApiOperation

@ApiParam

案例

@Data
@ApiModel(value = "获取用户列表DTO")
public class UserListReqDTO extends PageQuery {/*** 部门ID、前端传递 应要求 查询负责部门*/@ApiModelProperty(value = "部门ID")private Long organizeId;/*** 姓名*/@ApiModelProperty(value = "姓名")private String userName;/*** 角色ID*/@ApiModelProperty(value = "角色ID")private Long roleId;/*** 部门层级*/@ApiModelProperty(value = "部门层级")private Integer tagCode;
}

@Slf4j
@Validated
@RestController
@RequestMapping("/download-task")
@Api(value = "下载中心", tags="release_2412")
public class DownloadTaskController {private final DownloadTaskService downloadTaskService;private final DownloadManager downloadManager;private final UserService userService;public DownloadTaskController(DownloadTaskService downloadTaskService, DownloadManager downloadManager, UserService userService) {this.downloadTaskService = downloadTaskService;this.downloadManager = downloadManager;this.userService = userService;}/*** 下载中心新增任务** @param reqDTO*/@PostMapping("/save")@ApiOperation(value = "新增任务", notes = "保存下载任务，状态为下载中")public ApiResponse save(@RequestBody @Validated @ApiParam("下载任务实体") DownloadTaskReqDTO reqDTO) {downloadTaskService.addDownloadTask(reqDTO);return ApiResponse.createBySuccess();}@PostMapping("/submit")@ApiOperation(value = "提交审核", notes = "提交导出任务审核", tags = {"2502"})public ApiResponse<Long> submit(@RequestBody @Validated @ApiParam("提交审核实体") DownloadTaskReqDTO reqDTO) {return ApiResponse.createBySuccess(downloadTaskService.submit(reqDTO));}}

5. 接口调用

6.请求头

• 有时候我们的接口是需要获取请求头信息的，这样的话就还需要在 swagger 配置中添加请求头的配置。

    @Beanpublic Docket docket() {// 设置请求头List<Parameter> parameters = new ArrayList<>();parameters.add(new ParameterBuilder().name("token") // 字段名.description("token") // 描述.modelRef(new ModelRef("string")) // 数据类型.parameterType("header") // 参数类型.defaultValue("default value") // 默认值：可自己设置.hidden(true) // 是否隐藏.required(false) // 是否必须.build());// 创建一个 swagger 的 bean 实例return new Docket(DocumentationType.SWAGGER_2).groupName("mike") // 修改组名为 "mike"// 配置接口信息.select() // 设置扫描接口// 配置如何扫描接口.apis(RequestHandlerSelectors.basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用).paths(PathSelectors.any() // 满足条件的路径，该断言总为true).build()// 添加请求头参数.globalOperationParameters(parameters);}

比如接口：

    @GetMapping(value = "/get-token")@ApiOperation(value = "获取请求头中的token信息")public void getToken(@RequestHeader(value = "token",required = false) String token) {// 直接获取 token 信息System.out.println("token = " + token);// 通过代码获取ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();if (servletRequestAttributes != null) {HttpServletRequest request = servletRequestAttributes.getRequest();String header = request.getHeader("token");System.err.println("header = " + header);}}