SpringBoot 整合 swagger2 实现快速测试和快速生成 API 文档

现在很多项目都是前后端分离模式，所以在开发团队中经常需要写 API 文档，便于前后端开发对接。

若手写 API 文档，则有以下几个痛点：

• 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
• 文档编写需要单独占用时间，占用人力
• 接口文档太多，不好管理
• 不能直接在线测试接口，通常需要使用工具，比如 postman

SpringBoot 项目整合 swagger2 插件，可以快速生成接口文档，便于测试接口。当然 swagger2 也有缺点，最明显的就是代码移入性比较强。下面简单介绍下如何在项目中使用 swagger2。

一、在 pom.xml 里面添加 jar 依赖

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

二、添加配置文件 Swagger2Config.java

package com.rabbit.producer.config;

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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;

/**
 * Swagger2 插件配置
 *
 * @EnableSwagger2 表示开启Swagger
 * @ConditionalOnProperty 这里的属性 key 是 swagger.enabled，havingValue 是期望值，只有在其值等于期望值的时候，才会生效。
 * 也就是说，swagger.enabled 只能为 true 的时候才会生效，其他值或不设值，都不会生效的。
 */
@Configuration
@EnableSwagger2
@ConditionalOnProperty(prefix = "swagger", value = {"enabled"}, havingValue = "true")
public class Swagger2Config {

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot整合RabbitMQ系统Restful API")
                .description("SpringBoot整合RabbitMQ系统Restful API")
                .version("1.0")
                .build();
    }

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                // 扫描的路径包
                .apis(RequestHandlerSelectors.basePackage("com.rabbit.producer.controller"))
                // 指定路径处理PathSelectors.any()代表所有的路径
                .paths(PathSelectors.any()).build().pathMapping("/");
    }
}

三、application.properties 配置文件中设置是否启用 swagger

server.port=8888
swagger.enabled=true

四、新建请求参数对象 EventMessage.java

package com.rabbit.common.entity;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * 消息类
 */
@Data
@NoArgsConstructor
@AllArgsConstructor
public class EventMessage implements Serializable {

    private static final long serialVersionUID = -9203358002484642594L;

    private String name;

    private String desc;
}

五、新建测试类 TestContronller.java

package com.rabbit.producer.controller;

import com.rabbit.common.entity.EventMessage;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

/**
 * 测试 swagger2 插件生成 restful 文档
 */
@RestController
@Slf4j
public class TestContronller {

    @ApiOperation(value = "测试swagger2插件的使用", notes = "swagger2插件测试方法")
    @ApiImplicitParam(name = "message", value = "消息类", required = true, dataType = "EventMessage")
    @PostMapping("/testSwagger")
    public String testSwagger(@RequestBody EventMessage message) {
        log.info("desc:[{}];name:[{}]", message.getDesc(), message.getName());
        return "HelloWorld";
    }
}

六、启动项目并访问

启动项目并用浏览器访问路径：http://127.0.0.1:8888/swagger-ui.html，页面如下图所示。

• 红色方框：接口文档。单击即可打开查看。
• 绿色方框：接口请求参数 EventMessage。
• 蓝色方框：项目的测试方法列表。

具体接口测试步骤如下：

1. 选择一个测试方法，单击绿色横条区域，点击右上角 Try it out 按钮。
   
2. 按下图中顺序，依次编辑请求参数、单击Cancel、单击 Excute 按钮，即可完成测试。
   测试返回应答数据如下图所示。
   

七、swagger2 注解说明

swagger2 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息等。

@ApiOperation(value = “说明方法的用途、作用”, notes = “方法的备注说明”）(其他参数可参考源码)
@Api：修饰整个类，描述Controller的作用
@ApiResponse：HTTP响应其中1个描述
@ApiResponses：HTTP响应整体描述
@ApiIgnore：使用该注解忽略这个API
@ApiError ：发生错误返回的信息

@ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息，用法示例：
@ApiImplicitParam(name = “参数名”, value = “参数的汉字说明、解释”, required = true, dataType = “参数类型，默认String，其它值自行填写”)
其中 required：参数是否必传，取值为 true or false。

@ApiImplicitParams：用于多个请求参数的方法，包含多个 @ApiImplicitParam，用法示例：
@ApiImplicitParams({
@ApiImplicitParam(name=“name”, value=“用户名”, dataType=“string”, paramType = “query”),
@ApiImplicitParam(name=“id”, value=“用户id”, dataType=“long”, paramType = “query”)
})