springboot集成swagger-ui 2创建可用的接口文档

前言：

目前网上已经有 很多关于springboot 集成swagger ui的博客，但大部分都是最基本的集成使用，想要用来完全代替现有的接口文档还需要许多的配置改进，写这篇博客的目的就是记录一次使用swagger ui完全 替代现有的接口文档的过程，同时也给有相同需求的同学一些参考，个人水平有限，如有不足或错误的地方还请批评指正。话不多说，进入正题。

springboot 集成 swagger ui

和大多数博客一样首选引入依赖

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

创建基础配置文件，稍后再来针对具体需求修改该配置类

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import io.swagger.annotations.ApiOperation; 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) .useDefaultResponseMessages(false) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //这里采用包含注解的方式来确定要显示的接口 //.apis(RequestHandlerSelectors.basePackage("com.xx.xx.controller")) //这里采用包扫描的方式来确定要显示的接口 .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Cmis clien for java") .description("desc") .version("1.0") .build(); } }

创建 contoller类

@RestController @RequestMapping("/cmis") @Api(value="CmisController相关api",description="cmis相关api") public class CmisController { @Resource CmisFolderService cmisFolderService; @ApiOperation("创建文件夹") @ApiImplicitParams({ @ApiImplicitParam(paramType="query",name="cmisToken",dataType="String",required=true,value="cimstoken"), @ApiImplicitParam(paramType="query",name="folderName",dataType="String",required=true,value="文件夹名称"), @ApiImplicitParam(paramType="query",name="parentObjectId",dataType="String",required=true,value="父节点objectId") }) @RequestMapping(value="/createFolder",method=RequestMethod.GET) public RespObj<FoxitCmisObject> getUser(@RequestParam("folderName") String folderName, @RequestParam("cmisToken") String cmisToken, @RequestParam("parentObjectId") String parentObjectId) { RespObj<FoxitCmisObject> respObj = new RespObj<FoxitCmisObject>(); FoxitCmisObject foxitCmisObject = cmisFolderService.createFolder(cmisToken, parentObjectId, folderName); respObj.setData(foxitCmisObject); return respObj; } }

启动后访问 swagger-ui.html 显示如下：

到目前为止已经满足基本的接口文档需求了、Example Value显示的内容根据RespObj<FoxitCmisObject>  使用泛型来实现，RespObje类如下

public class RespObj<T> implements Serializable { /** * @Fields serialVersionUID : TODO */ private static final long serialVersionUID = 1L; private int ret; private String msg; private T data; public RespObj( ) { this.ret = 0; this.msg = "success"; } public RespObj(T data) { this(); this.data = data; } public int getRet() { return ret; } public void setRet(int ret) { this.ret = ret; } public String getMsg() { return msg; } public void setMsg(String msg) { this.msg = msg; } public T getData() { return data; } public void setData(T data) { this.data = data; } }

1.给返回字段添加注释说明的需求，通过给属性添加@ApiModelProperty来实现注释功能， 如下

@ApiModelProperty(value="返回码") private int ret; @ApiModelProperty(value="错误提示") private String msg;

效果如下

2.返回全部的 状态码

在大部分的 接口文档中，都会有一个 表格用了列举所有的返回code, 那swagger ui中怎么实现呢，我是通过修改apiInfo()中的代码，直接拼接表格显示在网页顶端desc部位，代码如下：

private ApiInfo apiInfo() { StringBuilder sb = new StringBuilder("<table>"); sb.append("<caption>返回Ret状态码</caption>"); int i=1; for (ResultEnum resultEnum : ResultEnum.values()) { if(i%6==1){ sb.append("<tr>"); } sb.append("<td>"); sb.append(resultEnum.getCode()); sb.append("</td>"); sb.append("<td>"); sb.append(resultEnum.getMsg()); sb.append("</td>"); if(i%6==0){ sb.append("</tr>"); } i++; } sb.append("</table>"); return new ApiInfoBuilder() .title("Cmis clien for java") .description(sb.toString()) .version("1.0") .build(); }

其中ResultEnum为所有错误 类型的枚举类，页面效果如下：

3.服务器与本地开发环境contextPath 不一致问题

服务器上使用nginx做反向代理， 访问地址为 http://xxx.com/platform/  指向该项目；即本地开发使用http://localhost:8080/swagger-ui.html,而服务器 上需要使用http://xxx.cocm/platform/swagger-ui.html,使用一个动态pathMapping参数来初始化swagger,代码如下:

@Value("${swagger.pathMapping}") String pathMapping; @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .useDefaultResponseMessages(false).pathMapping(pathMapping) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //这里采用包含注解的方式来确定要显示的接口 //.apis(RequestHandlerSelectors.basePackage("com.fz.hr.modules.system.controller")) //这里采用包扫描的方式来确定要显示的接口 .paths(PathSelectors.any()) .build(); }

swagger.pathMapping 根据profile不同设置。 

4.屏蔽生产环境 swagger-ui

在配置类 上添加注解@Profile({"dev","test"}) //正式线屏蔽，只支持 dev和test

@Configuration @EnableSwagger2 @Profile({"dev","test"}) //正式线屏蔽 public class SwaggerConfig {

到此为止，已经能够替换掉我们之前写的接口文档了。