Swagger,SpringBoot,SpringMVC,Yapi的集成

背景

我们公司接口管理工具用的是Yapi，但是Yapi还是需要后端开发人员分配较多额外的精力去维护接口文档的信息，于是就产生了这篇博客。

Swagger简介

官网

Swagger是一个简单但功能强大的API表达工具。它具有地球上最大的API工具生态系统，数以千计的开发人员，使用几乎所有的现代编程语言，都在支持和使用Swagger。使用Swagger生成API，我们可以得到交互式文档，自动生成代码的SDK以及API的发现特性等。

Swagger原生的测试接口功能是和相应业务项目绑定的，对于我们公司来说测试环境有多台服务器，所以项目部署服务器可能会随时更换，这样Swagger测试UI地址也就随着经产变更了，这会对前端人员造成困惑。而且Yapi的接口测试功能要比Swagger要丰富，而且还支持mock。所以，我们只用Swagger的文档自动生成功能，然后把接口文档导入Yapi。

Swagger Demo

SpringBoot+Swagger

pom.xml

    io.springfox
    springfox-swagger2
    2.9.2

对于Java来说，目前springfox是最好的选择，它内部会自动解析Spring容器中Controller暴露出的接口，并且也提供了一个界面用于展示或调用这些API（由于我们不用Swagger的接口测试功能，所以并没有引用相应依赖）。

Swagger2配置类

package com.demo.hello;
 
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.context.properties.ConfigurationProperties;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
/**
 * @author: 云若
 * @date: 2018/8/30
 */
@Configuration
@EnableSwagger2
@ConfigurationProperties(prefix = "swagger")
public class Swagger2 {
 
    private static final String BASE_PACKAGE = "com.demo";
    @Value("${swagger.enable}")
    private boolean enableSwagger;
 
    @Bean
    public Docket helloDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                //用于分组功能
                .groupName("hello")
                //注册整体api信息
                .apiInfo(apiInfo())
                //swagger功能是否启用
                .enable(enableSwagger)
                .select()
                //指定扫描的包
                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                //设置此组只匹配hello/**的请求
                .paths(PathSelectors.ant("/hello/**"))
                .build();
    }
 
    @Bean
    public Docket testDocket() {
        return new Docket(DocumentationType.SWAGGER_2).groupName("test")
                .apiInfo(apiInfo())
                .enable(enableSwagger)
                .select()
                .apis(RequestHandlerSelectors.basePackage(BASE_PACKAGE))
                .paths(PathSelectors.ant("/test/**"))
                //                .paths(PathSelectors.any())
                .build();
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("test")
                .contact(new Contact("yunruo", "", ""))
                .version("1.0.0")
                .build();
    }
 
}

本配置考虑了我们公司需要以及可能需要的功能
分组功能。开发新接口时可能已经有很多老接口，但是我们可能只想往Yapi上传本次新开发的接口信息。可以用Swagger的分组功能，指定某个分组只匹配我们新开发的接口路径，然后只获取这个分组的接口信息。比如说我想获得hello分组的接口信息（项目ip:端口/v2/api-docs?group=分组名）：

http://localhost:8080/v2/api-docs?group=hello

动态开关Swagger接口功能。在生产环境出于安全角度考虑，我们需要关闭Swagger接口功能。在测试环境，我们需要开启以生成接口文档。

Swagger本身提供开关功能，再加上Spring Boot或者Maven的多环境配置功能就可以做到。

application.yml配置：

swagger:
  enable: true

接口代码

HelloController

package com.demo.hello;
 
import com.demo.test.TestResp;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;
 
@RestController
@Api(value = "hello相关接口", description = "hello")
public class HelloController {
 
    @ApiOperation(value = "欢迎接口", notes = "欢迎接口",response = TestResp.class)
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public TestResp hello(@ApiParam(value = "hello", required = true)
            @RequestParam(required = true)String index,@ApiParam(value = "hello", required = true)
    @RequestParam(required = true)String index2) {
        return new TestResp();
    }
 
}

TestController

package com.demo.test;
 
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;
 
/**
 * @author: 云若
 * @date: 2018/8/30
 */
@RestController
@Api(value = "test相关接口", description = "test")
public class TestController {
 
    @ApiOperation(value = "test接口", notes = "test接口", response = TestResp.class)
    @RequestMapping(value = "/test", method = RequestMethod.POST)
    public TestResp test(@RequestBody TestParam testParam) {
        return new TestResp();
    }
}

TestParam

package com.demo.test;
 
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
 
/**
 * @author: 云若
 * @date: 2018/8/30
 */
@ApiModel(value = "test", description = "test参数")
public class TestParam {
 
    @ApiModelProperty(value = "名字", required = true, dataType = "string")
    private String name;
 
    public String getName() {
        return name;
    }
 
    public void setName(String name) {
        this.name = name;
    }
}

TestResp

package com.demo.test;
 
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
 
/**
 * @author: 云若
 * @date: 2018/8/30
 */
@ApiModel(value = "test", description = "test响应")
public class TestResp {
    @ApiModelProperty(value = "欢迎语",dataType = "string")
    private String message;
 
 
    public String getMessage() {
        return message;
    }
 
    public void setMessage(String message) {
        this.message = message;
    }
}

更多注解应用参考：https://github.com/swagger-api/swagger-core/wiki/annotations

到这里SpringBoot+Swagger的配置就完了。

SpringMVC+Swagger

公司有很多老项目还没用SpringBoot，所以也调研了一下SpringMVC+Swagger的配置方式。网上的教程有一些坑，很多是是而非的点，经测试以下应该是最简配置。

pom.xml

    io.springfox
    springfox-swagger2
    2.9.2


    com.google.guava
    guava
    20.0

 
    com.fasterxml.jackson.core
    jackson-databind
    2.9.5

 

    com.fasterxml.jackson.core
    jackson-core
    2.9.5

 

    com.fasterxml.jackson.core
    jackson-annotations
    2.9.5

Swagger版本是最新版本，guava和jackson版本是依据Swagger的最新版本配置的。

Swagger2配置类

该配置类和上面的SpringBoot+Swagger的配置方式相同，只是类上注解不同，代码引用配置文件属性的方式也大同小异，在此只贴出注解配置。

@Configuration
@EnableWebMvc
@EnableSwagger2
@PropertySource(value = "classpath:sys.properties")

接口代码

注解的使用方式也和上面相同，略过。

Swagger数据导入Yapi

获取接口信息

经过上面的配置，调用http://localhost:8080/v2/api-docs?group=test，可以得到以下数据，把它保存在一个json文件里（我们目前的Yapi版本只支持文件上传）。

{
    "swagger": "2.0",
    "info": {
        "description": "test",
        "version": "1.0.0",
        "title": "Spring Boot中使用Swagger2构建RESTful APIs",
        "contact": {
            "name": "yunruo"
        }
    },
    "host": "localhost:8080",
    "basePath": "/",
    "tags": [
        {
            "name": "test-controller",
            "description": "test"
        }
    ],
    "paths": {
        "/test": {
            "post": {
                "tags": [
                    "test-controller"
                ],
                "summary": "test接口",
                "description": "test接口",
                "operationId": "testUsingPOST",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "*/*"
                ],
                "parameters": [
                    {
                        "in": "body",
                        "name": "testParam",
                        "description": "testParam",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/test"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/test"
                        }
                    },
                    "201": {
                        "description": "Created"
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "Forbidden"
                    },
                    "404": {
                        "description": "Not Found"
                    }
                },
                "deprecated": false
            }
        }
    },
    "definitions": {
        "test": {
            "type": "object",
            "required": [
                "name"
            ],
            "properties": {
                "message": {
                    "type": "string",
                    "description": "欢迎语"
                },
                "name": {
                    "type": "string",
                    "description": "名字"
                }
            },
            "title": "test",
            "description": "test参数"
        }
    }
}

Yapi数据导入

image

下面还有个开启数据同步开关。建议更新以前的接口文档时开启，新增时关闭。

源代码地址

springboot-swagger

springmvc-swagger
之前虽然有简单使用过Swagger，但是并没有仔细研究过，所以文章描述可能有错或者不准确。文章中有错误欢迎指正，使用中有疑问欢迎讨论。