总结之Swagger——SpringBoot集成 Swagger 管理 API 文档

swagger介绍

官网介绍https://swagger.io/docs/specification/about/

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。
Swagger 的优势
支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

一、 项目中集成 Swagger——pom

Pom.xml 添加Maven依赖

!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
    
        io.springfox
        springfox-swagger-ui
        2.9.2
    

 
    
       io.springfox
       springfox-swagger2
       2.9.2
    

二、 Swagger配置文件

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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author liuzonghua
 * @Package com.example.rabbitmq_cons_demo.swagger2
 * @Description:
 * @date 2020/4/24 15:28
 */
@Configuration
@EnableSwagger2
public class Swagger2Configuration {

    /**
     * api接口包扫描路径
     */
    public static final String SWAGGER_SCAN_BASE_PACKAGE = "com.example.rabbitmq_cons_demo.swagger2.api";

    public static final String VERSION = "1.0.0";

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("1.测试通信")
                .select()
                .apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }
    @Bean
    public Docket socketRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("2.socket通信")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.rabbitmq_cons_demo.swagger2.api"))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的Swagger服务") //设置文档的标题
                .description("我的Swagger服务 API 接口文档") // 设置文档的描述
                .version(VERSION) // 设置文档的版本信息-> 1.0.0 Version information
                .termsOfServiceUrl("http://www.baidu.com") // 设置文档的License信息->1.3 License information
                .build();
    }
}

三、使用 Swagger 生成文档

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author liuzonghua
 * @Package com.example.rabbitmq_cons_demo.swagger2.api
 * @Description:
 * @date 2020/4/24 15:53
 */
@RestController
@Api(value = "/apiP", tags = "生产者进程",description = "生产者进程API接口")

@RequestMapping("/apiP")
public class ProducerController {

  @Api(value = "/apiP2", tags = "生产者进程2",description = "生产者进程API接口2")
    @RequestMapping("/sendTest")
    @ResponseBody
    public String sendTest(String text){
        return text;
    }
}

来来来,看看代码实现了什么功能

其中一在配置文件中@Bean实现，作为一个版本
可以配置名称、包等
其中二在配置文件中@Bean方法中apiInfo实现，文件标题信息等
其三是请求方法，在Controller中@Api和@ApiOperation实现。为接口信息

@ApiOperation("闸机信息所有列表")
public R list(@RequestParam(required = false) @ApiParam(value = "闸机名称（搜索使用）") String name,
              @RequestParam(required = false) @ApiParam(value = "景区id") String scenicId) {

页面强制必填
在后台采用对象接收参数时，Swagger自带的工具采用的是JSON传参， 测试时需要在参数上加入@RequestBody,正常运行采用form或URL提交时候请删除。

@ApiOperation("监控信息分页列表")	
@ApiImplicitParam(paramType = "query", dataType = "String", name = "groupId", value = "wifi分组", required = true)
public R list(@RequestParam(required = false) @ApiParam(value = "监控名称（搜索使用）") String name,
              String groupId,
              @RequestParam(required = false) @ApiParam(value = "当前页码,默认1") String pageNum,
              @RequestParam(required = false) @ApiParam(value = "每页条数，默认10") String pageSize) {

其四是请求参数
也可以是对象

@ApiModel
public class Apple {
    @ApiModelProperty(value = "苹果id",required = true)
    private String id;
    @ApiModelProperty(value = "苹果名称",required = true)
    private String name;
    @ApiModelProperty(value = "苹果状态",required = true)
    private int status;

常用注解

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