swagger 快速生成接口测试文档详解及注意要点

Swagger使用总结

1. Swagger是什么？

官方说法：Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

个人觉得，swagger的一个最大的优点是能实时同步api与文档。在项目开发过程中，发生过多次：修改代码但是没有更新文档，前端还是按照老旧的文档进行开发，在联调过程中才发现问题的情况（当然依据开闭原则，对接口的修改是不允许的，但是在项目不稳定阶段，这种情况很难避免）。

2. spring boot 集成 Swagger

目前维护的系统是基于springboot框架开发的，因此本文会详细描述springboot与swagger集成的过程。

3，Swagger使用步骤：

3.1 导入相关的maven依赖


io.springfox

springfox-swagger2

2.5.0

io.springfox

springfox-swagger-ui

2.5.0

io.springfox

springfox-staticdocs

2.5.0


3.2 创建相关实体，controller，响应对象，主要看其中的注解的使用。

1 ，@Api(description = "用户相关接口文档")每个controller上的注解，表示这个controller主要的业务模块

2，@ApiOperation(value = "用户首页", notes = "访问页面")每个方法的注解，表示这个方法的业务功能是什么

3， @ApiParam(name = "userName",value = "用户昵称",required = true)方法参数注解，表示这个在这个业务方法中的名称，生成后的文档对该字段的说明，同样支持对象类型（引用类型），通过@ApiModelProperty(value = "用户id", required = true)来说明引用类型每个属性的作用。

4，@RequestHeader("token") String token 这个注解可以获取和设置header的参数，如用户身份签名。

controller

package org.kewei.zhang.controllers;

import io.swagger.annotations.Api;

import io.swagger.annotations.ApiOperation;

import io.swagger.annotations.ApiParam;

import org.kewei.zhang.Beans.TbTest;

import org.kewei.zhang.entites.Constants;

import org.kewei.zhang.entites.Result;

import org.kewei.zhang.entites.UserVo;

import org.kewei.zhang.mapper.TbTestMapper;

import org.kewei.zhang.utils.DateUtil;

import org.springframework.beans.factory.annotation.Autowired;

import org.springframework.web.bind.annotation.*;

import java.text.ParseException;

import java.util.ArrayList;

import java.util.Date;

import java.util.List;

import java.util.Random;

import java.util.concurrent.ExecutorService;

import java.util.concurrent.Executors;

/**

* @author : kewei.zhang

* @Date: 2017/10/19

* @Time: 下午3:00

* Description: 用于处理所有天网案件action的统一入口

*/

@SuppressWarnings("ALL")

@RestController

@RequestMapping("/case")

@Api(description = "用户相关接口文档")

public class SnCaseController extends BaseController {

@Autowired

private TbTestMapper tbTestMapper;

@GetMapping("/index")

@ApiOperation(value = "用户首页", notes = "访问页面")

public String index() {

TbTest tbTest = new TbTest();

tbTest.setAge(1);

tbTest.setBrithday(new Date());

tbTest.setHigh(172);

tbTest.setIsboy((short) 1);

tbTest.setName("张克巍");

tbTest.setSchool("皖西学院");

tbTest.setWigth(158);

tbTestMapper.insert(tbTest);

return "index";

}

@RequestMapping(value = "/add", method = RequestMethod.POST)

@ApiOperation(value = "添加用户", notes = "增加用户")

public Result add(@ApiParam(name = "token", value = "token",required = true) @RequestParam(name = "token", required = true) String token,

@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,

@ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile,

@ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) {

return new Result(Constants.SUCCESS,Constants.MSG_SUCCESS,new UserVo());

}

@RequestMapping(value = {"/toAdd","/testAdd"}, method = RequestMethod.GET)

@ApiOperation(value = "用户添加", notes = "用户增加")

public Result toAdd(@ApiParam(name = "token", value = "token",required = true) @RequestParam(name = "token", required = true) String token,

@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,

@ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile,

@ApiParam(required = true, name = "email", value = "邮箱") @RequestParam(name = "email", required = true) String email ) {

return new Result(Constants.SUCCESS,Constants.MSG_SUCCESS,new UserVo());

}

@RequestMapping(value = "/update", method = RequestMethod.POST)

@ApiOperation(value = "更新用户", notes = "用户更新")

public Result update(@ApiParam(name = "user", value = "user",required = true)@RequestBody UserVo userVo ) {

return new Result(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

}

@RequestMapping(value = "/getHeader", method = RequestMethod.POST)

@ApiOperation(value = "获取用户头部信息", notes = "获取用户头部信息")

public Result getHeader(@ApiParam(name = "token", value = "用户身份",required = true)@RequestHeader("token") String token,

@ApiParam(name = "userName",value = "用户昵称",required = true)@RequestParam(name = "userName",required = true)String userName,

@ApiParam(name = "mobile",value = "手机",required = true)@RequestParam(name = "mobile",required = true)String mobile) {

UserVo userVo= new UserVo();

userVo.setUserName(token+userName+mobile);

return new Result(Constants.SUCCESS,Constants.MSG_SUCCESS,userVo);

}

}

bean 这里需要注意，如果有boolean类型，要为其添加getXX

X和setXXX方法，不是isXXX，因为swagger不识别isXXX

package org.kewei.zhang.entites;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

/**

* @author: kewei.zhang

* @Date: 2017/12/5

* @Time: 下午3:15

* Description:

*/

@ApiModel(value = "用户信息")

public class UserVo {

@ApiModelProperty(value = "用户id", required = true)

private long userId=10;

@ApiModelProperty(value = "昵称", required = true)

private String userName="张克巍";

public long getUserId() {

return userId;

}

public void setUserId(long userId) {

this.userId = userId;

}

public String getUserName() {

return userName;

}

public void setUserName(String userName) {

this.userName = userName;

}

}

响应实体

package org.kewei.zhang.entites;

import com.fasterxml.jackson.annotation.JsonInclude;

import io.swagger.annotations.ApiModel;

import io.swagger.annotations.ApiModelProperty;

import java.io.Serializable;

/**

* @author: kewei.zhang

* @Date: 2017/12/5

* @Time: 下午3:11

* Description:

*/

@ApiModel

@JsonInclude(JsonInclude.Include.NON_NULL)

public class Result implements Serializable {

private static final long serialVersionUID = 1L;

// 200成功

@ApiModelProperty(value = "错误码", name = "错误码")

private int code;

// 返回消息，成功为“success”，失败为具体失败信息

@ApiModelProperty(value = "错误码描述", name = "错误码描述")

private String desc;

// 返回数据

@ApiModelProperty(value = "数据对象", name = "数据对象")

private T data;

public Result() {

}

public Result(int code, String desc) {

this.code = code;

this.desc = desc;

}

public Result(int code, String desc, T data) {

this.code = code;

this.desc = desc;

this.data = data;

}

public int getCode() {

return code;

}

public void setCode(int code) {

this.code = code;

}

public String getDesc() {

return desc;

}

public void setDesc(String desc) {

this.desc = desc;

}

public T getData() {

return data;

}

public void setData(T data) {

this.data = data;

}

@Override

public String toString() {

return "Result{" +

"code=" + code +

", desc='" + desc + '\'' +

", data=" + data +

'}';

}

}

package org.kewei.zhang.entites;

/**

* @author: kewei.zhang

* @Date: 2017/12/5

* @Time: 下午3:13

* Description:

*/

public interface Constants {

////////////// 系统标识符 开始//////////////////

/**

* 错误 描述

*/

String MSG_ERROR = "error";

/**

* 成功 描述

*/

String MSG_SUCCESS = "OK";

////////////// 系统状态码 开始//////////////////

/**

* 请求失败

*/

int ERROR = 100;

/**

* 请求成功

*/

int SUCCESS = 200;

}

3.3 swagger添加配置信息@Configuration@EnableSwagger2

package org.kewei.zhang.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import org.springframework.stereotype.Component;

import springfox.documentation.builders.PathSelectors;

import springfox.documentation.builders.RequestHandlerSelectors;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.service.Contact;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**

* @author: kewei.zhang

* @Date: 2017/12/5

* @Time: 下午3:04

* Description:

*/

@Configuration

@EnableSwagger2

@Component

public class SwaggerConfig {

@Bean

public Docket userApi() {

return new Docket(DocumentationType.SWAGGER_2)

.groupName("用户")

.select()

.apis(RequestHandlerSelectors.basePackage("org.kewei.zhang.controller"))// 选择那些路径和api会生成document,每个controller都需要添加

.paths(PathSelectors.any()) // 对所有路径进行监控

.build()

.apiInfo(userInfo());

}

private ApiInfo userInfo() {

ApiInfo apiInfo = new ApiInfo("用户相关接口",//大标题

"用户有关的接口，包括增加删除用户",//小标题

"0.1",//版本

"上海",

new Contact("zkw", "", ""),// 作者

"swagger url",//链接显示文字

""//网站链接

);

return apiInfo;

}

}

3.4 在浏览器中输入http://ip:port/your-app-root/swagger-ui.html即可生成相应的文档并可以随时测试。

图片.png

图片.png

图中的文字说明都是通过之前的注解添加进去的

上述是完成生成api文档的具体步骤，但是有这样几个问题值得大家思考。

接口文档生成，需要嵌入我们的项目中，对我们的代码有侵入，这一点现在避免不了，而且我们只希望用户在我们的测试环境去测试，不希望生成环境去生成文档，如何解决这个问题，方法有两种，如下：

在配置中做管理

@Configuration

@EnableSwagger2

@EnableWebMvc

@ComponentScan("com.XXX.controller")

public class SwaggerConfig{

@Autowired

ConfigService configService;

@Bean

public Docket customDocket() {

if(configService.getServerEnv() == ServerEnvEnum.ONLINE) {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfoOnline())

.select()

.paths(PathSelectors.none())//如果是线上环境，添加路径过滤，设置为全部都不符合

.build();

}else {

return new Docket(DocumentationType.SWAGGER_2)

.apiInfo(apiInfo());

}

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder()

.title("XXX系统")

.description("XXX系统接口")

.license("")

.licenseUrl("")

.termsOfServiceUrl("")

.version("1.0.0")

.contact(new Contact("","", ""))

.build();

}

private ApiInfo apiInfoOnline() {

return new ApiInfoBuilder()

.title("")

.description("")

.license("")

.licenseUrl("")

.termsOfServiceUrl("")

.version("")

.contact(new Contact("","", ""))

.build();

}

}

另一种方式是：

修改一下依赖，为了编译通过，单独把swagger-annotations拿出来,线上环境把springfox-swagger-ui的依赖配置成是provided，这样可以实现http://localhost/swagger-ui.html访问404。但是：http://localhost/v2/api-docs和http://localhost/swagger-resources等接口依然能够访问，尽管是空的！

io.swagger

swagger-annotations

${springfox-swagger-anno.version}

io.springfox

springfox-swagger2

${springfox-swagger.version}

io.springfox

springfox-swagger-ui

${swagger.scope}

${springfox-swagger.version}

online

online

provided

作者：时之令

链接：http://www.jianshu.com/p/c8b5382c39dc

來源：简书

著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。

©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 206,126评论 6赞 481
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 88,254评论 2赞 382
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 152,445评论 0赞 341
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 55,185评论 1赞 278
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 64,178评论 5赞 371
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,970评论 1赞 284
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 38,276评论 3赞 399
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,927评论 0赞 259
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 43,400评论 1赞 300
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,883评论 2赞 323
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,997评论 1赞 333
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,646评论 4赞 322
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 39,213评论 3赞 307
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 30,204评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,423评论 1赞 260
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 45,423评论 2赞 352
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,722评论 2赞 345

推荐阅读更多精彩内容

  • swagger 快速生成接口测试文档详解及注意要点
    Swagger使用总结 1. Swagger是什么？ 官方说法：Swagger是一个规范和完整的框架，用于生成、描...
    时之令阅读 10,391评论 0赞 2
  • Spring Cloud
    Spring Cloud为开发人员提供了快速构建分布式系统中一些常见模式的工具（例如配置管理，服务发现，断路器，智...
    卡卡罗2017阅读 134,599评论 18赞 139
  • Java初级面试题
    1. Java基础部分 基础部分的顺序：基本语法，类相关的语法，内部类的语法，继承相关的语法，异常的语法，线程的语...
    子非鱼_t_阅读 31,581评论 18赞 399
  • AS遇到的问题
    Q 一些jar包提示Failed to resolve: com.squareup.retrofit:retrof...
    hp简书阅读 231评论 0赞 0
  • 14-08-2017
    “行动吧，遇见更好的自己” 面试是个技术活，懵懵懂懂接到要去面试的电话，在网络上匆忙查了一下公司的背景情况。其实并...
    SuperVicky阅读 122评论 0赞 0