问题描述

在团队开发中，一个好的 API 文档不但可以减少大量的沟通成本，还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节，并在程序员之间代代相传。

这种做法存在以下几个问题：

API 接口众多，细节复杂，需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等，想要高质量的完成这份文档需要耗费大量的精力；
难以维护。随着需求的变更和项目的优化、推进，接口的细节在不断地演变，接口描述文档也需要同步修订，可是文档和代码处于两个不同的媒介，除非有严格的管理机制，否则很容易出现文档、接口不一致的情况
接口测试不方便，一般只能借助第三方工具（如：Postman）来测试。

基本概念

Swagger2 是一个开源软件框架，从根本上解决上述问题。它作为一个规范和完整的框架，可以用于设计、生成、描述、调用和可视化 RESTful 风格的 Web 服务，使开发人员将大部分精力集中到业务中，而不是繁杂琐碎的文档中：

接口文档在线自动生成，文档随接口变动实时更新，节省维护成本。
支持在线接口测试，不依赖第三方工具。
将代码和文档融为一体。

Maven

<dependencies>...<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency>
</dependencies>

解决方案

配置类

Swagger2Configuration.java

package com.zstu.metrocity.config;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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;/*** @Author ShenTuZhiGang* @Version 1.0.0* @Date 2020-04-13 19:57* Swagger2 配置类*/
@Configuration
@EnableSwagger2
public class CustomSwagger2Config {@BeanDocket docket(){return new Docket(DocumentationType.SPRING_WEB).select()//配置需要扫描的controller位置.apis(RequestHandlerSelectors.basePackage("com.zstu.controller"))//配置路径.paths(PathSelectors.any())//构建.build()//文档信息.apiInfo(new ApiInfoBuilder()//描述.description("MetroCity RESTful API 文档")//联系人信息.contact(new Contact("申屠志刚",//名字"https://shentuzhigang.blog.csdn.net/",//网址"1600337300@qq.com"))//邮箱//版本.version("V1.0")//标题.title("MetroCity RESTful API 文档")//License.license("Apache 2.0")//License 网址.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0").build());}}

Swagger2Configuration.java 配置类的内容不多，配置完成后也很少变化，简单了解即可。

如上代码所示，通过 @Configuration 注解，让 Spring 加载该配置类。再通过 @EnableSwagger2 注解来启用Swagger2。成员方法 createRestApi 函数创建 Docket 的Bean之后，apiInfo() 用来创建该 Api 的基本信息（这些基本信息会展现在文档页面中）。select() 函数返回一个 ApiSelectorBuilder实例用来控制哪些接口暴露给 Swagger 来展现，本例采用指定扫描的包路径来定义，Swagger 会扫描该包下所有 Controller 定义的 API，并产生文档内容（除了被 @ApiIgnore 指定的请求）。

API 接口编写

在完成了上述配置后，其实已经可以产生文档内容，但是这样的文档主要针对请求本身，而描述主要来源于函数等命名产生，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。

@Api(description = "生产者进程API接口")
@RestController
@RequestMapping("/producer")
public class ActiveMQProducer {private static final Logger logger = LoggerFactory.getLogger(ActiveMQConsumer.class);@Value(value = "${mq.active.count-queue-name}")private String COUNT_QUEUE_NAME;@Value(value = "${mq.active.query-queue-name}")private String QUERY_QUEUE_NAME;@Autowiredprivate ActiveMQManager mqManager;@ApiOperation(value="发送解析文本", notes="发送解析文本", produces="application/json")@RequestMapping(value="/sendText", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)public String sendText(@RequestBody String text) {logger.info("发送的文本内容：{}", text);try {mqManager.sendMsg(COUNT_QUEUE_NAME, text);} catch (Exception e){e.printStackTrace();logger.error(e.getMessage());}return "SUCESS";}@ApiOperation(value="查询单词计数", notes="查询单词计数", produces="application/json")@ApiImplicitParam(name = "word", value = "单词", paramType = "query", required = true, dataType = "String")@RequestMapping(value="/queryWordCount", produces={ MediaType.APPLICATION_JSON_UTF8_VALUE }, consumes={ MediaType.APPLICATION_JSON_UTF8_VALUE }, method=RequestMethod.POST)public String queryWordCount(@RequestBody String word) {logger.info("查询单词计数：{}", word);try {mqManager.sendMsg(QUERY_QUEUE_NAME, word);} catch (Exception e){e.printStackTrace();logger.error(e.getMessage());}return "SUCESS";}
}

本接口示例了 @ApiOperation 和 @ApiImplicitParam 两个注解的使用。

Swagger 通过注解定制接口对外展示的信息，这些信息包括接口名、请求方法、参数、返回信息等。更多注解类型：

@Api：修饰整个类，描述Controller的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiProperty：用对象接收参数时，描述对象的一个字段
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息
@ApiImplicitParam：描述一个请求参数，可以配置参数的中文含义，还可以给参数设置默认值
@ApiImplicitParams：描述由多个 @ApiImplicitParam 注解的参数组成的请求参数列表

启动 SpringBoot 应用

SpringBoot 启动成功后，访问 http://localhost:8080/swagger-ui.html

展开类维度的接口列表，如 active-mq-producer，页面会列出该类中定义的所有接口。点击任意接口，可查看该接口的 url 路径、请求类型、参数描述和返回码说明等信息。

点击右上角的 “Try it out！”按钮，录入请求信息，点击 Execute 按钮完成一次请求调用！

Spring Security 中的配置

Spring Boot 项目中如果集成了 Spring Security，在不做额外配置的情况下，Swagger2 文档会被拦截。解决方法是在 Security 的配置类中重写 configure 方法添加白名单即可：

@Override
public void configure ( WebSecurity web) throws Exception {web.ignoring().antMatchers("/swagger-ui.html").antMatchers("/v2/**").antMatchers("/swagger-resources/**");
}

参考文章

https://www.jianshu.com/p/c79f6a14f6c9

Spring Boot——集成Swagger2相关推荐

Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
Spring Boot 集成 Swagger2，构建强大的 API 文档
前言不管你是从事前端还是后端开发,相信都难免被接口文档折磨过.如果你是一个前端开发者,可能你会经常发现后端给的接口文档跟实际代码有所出入.而假设你是一个后端开发者,你可能又会觉得自己开发后端接口已经 ...
软件架构-Spring boot集成模板引擎swagger2实现
上次说过springboot其实就是一个CI工具,如何体验出来CI的作用就是持续集成,它可以集成各种的工具,这里说说关于模板的集成引擎和Swagger. (一)Spring boot 集成模板引擎实现 ...
Spring Boot 集成 Swagger 生成 RESTful API 文档
原文链接: Spring Boot 集成 Swagger 生成 RESTful API 文档简介 Swagger 官网是这么描述它的:The Best APIs are Built with Swa ...
Spring Boot集成Swagger
Spring Boot集成Swagger @(Swagger)[swagger, springfox, springboot] Spring Boot集成Swagger 前言基本概述案例引入依赖 ...
从零搭建一个 Spring Boot 开发环境！Spring Boot+Mybatis+Swagger2 环境搭建
从零搭建一个 Spring Boot 开发环境!Spring Boot+Mybatis+Swagger2 环境搭建本文简介为什么使用Spring Boot 搭建怎样一个环境开发环境导入快速启动 ...
Spring Boot系列六 Spring boot集成mybatis、分页插件pagehelper
1. 概述本文的内容包括如下内容: Spring Boot集成mybatis Spring Boot集成pagehelper分页插件,定义分页的相关类实现工具类:model转dto,实现数据层和传 ...
从零搭建开发脚手架 Spring Boot集成Mybatis-plus之一
文章目录简介特性框架结构依赖集成依赖配置编码开始使用核心功能代码生成器添加依赖编码编写配置自定义模板引擎自定义代码模板自定义属性注入字段其他信息查询注入实战总结常 ...
Spring Boot集成Swagger导入YApi@无界编程
接口APi开发现状现在开发接口都要在类似YApi上写文档,这样方便不同的团队之间协作,同步更新接口,提高效率. 但是如果接口很多,你一个个手工在YApi去录入无疑效率很低. 如果是使用Spring ...

Spring Boot——集成Swagger2