Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档

引言

　　在做服务端开发的时候，难免会涉及到API 接口文档的编写，可以经历过手写API 文档的过程，就会发现，一个自动生成API文档可以提高多少的效率。

　　以下列举几个手写API 文档的痛点：

• 文档需要更新的时候，需要再次发送一份给前端，也就是文档更新交流不及时。
• 接口返回结果不明确
• 不能直接在线测试接口，通常需要使用工具，比如postman
• 接口文档太多，不好管理

　　Swagger也就是为了解决这个问题，当然也不能说Swagger就一定是完美的，当然也有缺点，最明显的就是代码移入性比较强。

系列文档目录

Spring Boot 项目学习 (一) 项目搭建

Spring Boot 项目学习 (二) MySql + MyBatis 注解 + 分页控件 配置

Spring Boot 项目学习 (三) Spring Boot + Redis 搭建

Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档

配置 Swagger

　　1. 修改pom.xml文件，添加依赖

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

　　2. 添加Swagger2的配置文件Swagger2Config

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.springboot.controller")) //需要注意的是这里要写入控制器所在的包
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("springboot利用swagger构建api文档")
                .description("简单优雅的restfun风格，https://www.cnblogs.com/jiekzou/")
                .termsOfServiceUrl("https://www.cnblogs.com/jiekzou/")
                .version("1.0")
                .build();
    }
}

　　如上代码所示，通过@Configuration注解，让Spring来加载该类配置。再通过@EnableSwagger2注解来启用Swagger2。

　　createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，本例采用指定扫描的包路径来定义，Swagger会扫描该包下所有Controller定义的API，并产生文档内容（除了被@ApiIgnore指定的请求）。

　　添加文档内容

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

package com.springboot.controller;

import com.github.pagehelper.PageInfo;
import com.springboot.entity.Church;
import com.springboot.service.ChurchService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@Api(value = "团契操作controller", description = "团契相关的操作", tags = {"团契模块校验接口"})
@RestController
@RequestMapping("/church")
public class ChurchController {
    @Autowired
    private ChurchService churchService;

    @ApiOperation(value = "获取指定团契信息", notes = "根据传入标识获取详细信息")
    @ApiImplicitParam(name = "churchId", value = "团契标识", required = true, dataType = "String", paramType = "path")
    @RequestMapping(value = "/get/{churchId}", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
    public String getChurch(@PathVariable String churchId) {
        Church church = churchService.get(churchId);
        return church.toString();
    }

    @ApiOperation(value = "获取团契列表", notes = "获取团契列表")
    @RequestMapping(value = "list", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
    public List<Church> list() {
        return churchService.list();
    }

    @ApiOperation(value = "分页获取团契列表", notes = "获取团契列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "page", value = "第几页", required = true, dataType = "Integer", paramType = "path"),
            @ApiImplicitParam(name = "pageSize", value = "每页取几条记录", required = true, dataType = "Integer", paramType = "path")
    })
    @RequestMapping(value = "/list/{page}/{pageSize}", method = RequestMethod.GET, produces = {"application/json;charset=UTF-8"})
    public PageInfo<Church> list(@PathVariable("page") int page, @PathVariable("pageSize") int pageSize) {
        return churchService.list(page, pageSize);
    }
}

swagger的相关注解

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

• @Api：修饰整个类，描述Controller的作用
• @ApiOperation：描述一个类的一个方法，或者说一个接口
• @ApiParam：单个参数描述
• @ApiModel：用对象来接收参数
• @ApiProperty：用对象接收参数时，描述对象的一个字段
• @ApiResponse：HTTP响应其中1个描述
• @ApiResponses：HTTP响应整体描述
• @ApiIgnore：使用该注解忽略这个API
• @ApiError ：发生错误返回的信息
• @ApiImplicitParam：一个请求参数
• @ApiImplicitParams：多个请求参数

启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html，最终运行效果如下