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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

对于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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>20.0</version>
</dependency>
 <dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>2.9.5</version>
</dependency>
 
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-core</artifactId>
    <version>2.9.5</version>
</dependency>
 
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-annotations</artifactId>
    <version>2.9.5</version>
</dependency>

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,但是并没有仔细研究过,所以文章描述可能有错或者不准确。文章中有错误欢迎指正,使用中有疑问欢迎讨论。

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 204,053评论 6 478
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 85,527评论 2 381
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 150,779评论 0 337
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 54,685评论 1 276
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 63,699评论 5 366
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 48,609评论 1 281
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 37,989评论 3 396
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 36,654评论 0 258
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 40,890评论 1 298
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,634评论 2 321
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,716评论 1 330
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 33,394评论 4 319
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 38,976评论 3 307
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,950评论 0 19
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,191评论 1 260
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 44,849评论 2 349
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 42,458评论 2 342

推荐阅读更多精彩内容

  • Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具(例如配置管理,服务发现,断路器,智...
    卡卡罗2017阅读 134,591评论 18 139
  • 今天,下午放学,女儿去辅导班写作业。我7点多去接她,去到女儿作业刚写完。老师正在帮她检查。回到家我看了一下孩子写的...
    非常完美音乐飞扬阅读 150评论 0 0
  • 乱词 静静的是时光的流浪,流浪将我在时光里遗忘,我抚摸不了你的寂寞和忧伤,偏要我痴心难理望江。 层楼上留下一段风光...
    滕木毅阅读 255评论 0 1
  • 汝果欲学诗, 功夫在诗外。 归根方知静, 知静见如来。
    十年一井阅读 145评论 0 0
  • 文/郑毛毛 刘逗逗,这次我真的不喜欢你了,我不爱你了。你好好爱你的简爱吧,我这样的疯女人更适合爱我的人。我...
    好吧_阅读 339评论 3 1