Spring-Boot快速集成Swagger插件（Api在线接口文档）

关于Swagger

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

当存在一个RESTful 的项目，需要和别人对接时，为了方便阅读的你提供的接口。引入Swagger后，关于输入参数、返回参数和请求方式，都可以清晰的看见。方便api文档的管理，同时需要的话还可以作为api的测试工具。

Spring-Boot集成Swagger

1.添加依赖

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

2.Swagger配置

这里我使用的配置类和yml配置文件去整合的

yml配置

# swagger config
com.dl.demo.plugin.swagger:
   enable: true
   scan.package: com.dl.demo.controller

配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${com.dl.demo.plugin.swagger.enable}")
    private boolean swaggerEnable;

    @Value("${com.dl.demo.plugin.swagger.scan.package}")
    private String scanPackage;

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnable)
                .apiInfo(apiInfo())
                .select()
                //为当前包路径
                .apis(RequestHandlerSelectors.basePackage(scanPackage))
                .paths(PathSelectors.any())
                .build();
    }
    //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //页面标题
                .title("Demo项目API一览")
                //创建人
                .contact(new Contact("DavidLei08", "https://github.com/DavidLei08/", "2686849744@qq.com"))
                //版本号
                .version("1.0")
                //描述
                .description("API 描述")
                .build();
    }

}

为了方便再不同环境下切换配置，我将swagger的enable和扫描包的配置抽出在ym配置文件中。
当需要禁用swagger时只需要将enable改成false,扫描包名可以根据实际情况修改。

3.controller层使用

@Api 标注当前controller类为api模块
@ApiOperation 标注当前方法为api接口
@ApiResponse 标注当前方法的响应状态和message信息
@ApiParam 标注当前方法的入力参数dto

/**
 * MqSendController
 * @author  DavidLei08
 */
@Api(value = "用户管理类")
@RestController
public class MqSendController {

    @Autowired
    private MqOperationService mqOperationService;


    @ApiOperation(value = "发送mq")
    @PostMapping("/sendmq")
    @ApiResponse(code = 200, message = "发送mq请求返回的dto")
    public BaseResponse sendMq(@ApiParam  @Valid  @RequestBody MqSendRequest request,
                               BindingResult result, HttpServletResponse httpResponse){
        BaseResponse response = new BaseResponse();
        if(!result.hasErrors()){
            try {
                mqOperationService.sendMq(request);
                response.setHttpStatus("200");
                response.setMessage("request is ok");
            } catch (Exception e){
                httpResponse.setStatus(500);
                response.setHttpStatus("500");
                response.setMessage("mq send failed");
            }
        } else {
            httpResponse.setStatus(401);
            response.setHttpStatus("401");
            response.setMessage("request formatter is wrong");
        }
        return  response;
    }

}

关于api的文档，可能需要显示，也可能不需要显示，比如error统一处理的controller就不需要对外暴露。
可以将 @Api 替换成 @ApiIgnore 表示api文档忽略当前类。当前类就不会出现再api文档中。

/**
 * MqSendController
 * @author  DavidLei08
 */
@ApiIgnore
//@Api(value = "用户管理类")
@RestController
public class MqSendController {

    @Autowired
    private MqOperationService mqOperationService;


    @ApiOperation(value = "发送mq")
    @PostMapping("/sendmq")
    @ApiResponse(code = 200, message = "发送mq请求返回的dto")
    public BaseResponse sendMq(@ApiParam  @Valid  @RequestBody MqSendRequest request,
                               BindingResult result, HttpServletResponse httpResponse){
        BaseResponse response = new BaseResponse();
        if(!result.hasErrors()){
            try {
                mqOperationService.sendMq(request);
                response.setHttpStatus("200");
                response.setMessage("request is ok");
            } catch (Exception e){
                httpResponse.setStatus(500);
                response.setHttpStatus("500");
                response.setMessage("mq send failed");
            }
        } else {
            httpResponse.setStatus(401);
            response.setHttpStatus("401");
            response.setMessage("request formatter is wrong");
        }
        return  response;
    }

}

4.输入dto使用

@ApiModel 表示当前类为api输入的model
@ApiModelProperty 表示当前字段为输入字段 -value 是解释 -example 是例子 -required 表示是否是必须字段

/**
 * MqSendRequest
 * @author DavidLei08
 */
@ApiModel(value = "mq发送传入信息model")
public class MqSendRequest implements Serializable {

    @NotNull
    @NotEmpty
    @ApiModelProperty(value = "mq类型-topic/queue", example = "topic",required = true)
    private String mqType;

    @NotNull
    @NotEmpty
    @ApiModelProperty(value = "发送目的地名", example = "float_01",required = true)
    private String toName;

    @NotNull
    @NotEmpty
    @ApiModelProperty(value = "发送信息内容", example = "test message",required = true)
    private String message;

    public String getMqType() {
        return mqType;
    }

    public void setMqType(String mqType) {
        this.mqType = mqType;
    }

    public String getToName() {
        return toName;
    }

    public void setToName(String toName) {
        this.toName = toName;
    }

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
}

swagger插件真心不错
不过代码中会多很多注解，看起来内容有点多，其实无关乎业务，哈哈!!