springboot集成swagger-ui 2创建可用的接口文档
前言：
目前网上已经有 很多关于springboot 集成swagger ui的博客，但大部分都是最基本的集成使用，想要用来完全代替现有的接口文档还需要许多的配置改进，写这篇博客的目的就是记录一次使用swagger ui完全 替代现有的接口文档的过程，同时也给有相同需求的同学一些参考，个人水平有限，如有不足或错误的地方还请批评指正。话不多说，进入正题。
springboot 集成 swagger ui
和大多数博客一样首选引入依赖
io.springfox
springfox-swagger2
2.7.0
io.springfox
springfox-swagger-ui
2.7.0
创建基础配置文件，稍后再来针对具体需求修改该配置类
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 getUser(@RequestParam("folderName") String folderName,
@RequestParam("cmisToken") String cmisToken,
@RequestParam("parentObjectId") String parentObjectId) {
RespObj respObj = new RespObj();
FoxitCmisObject foxitCmisObject = cmisFolderService.createFolder(cmisToken, parentObjectId, folderName);
respObj.setData(foxitCmisObject);
return respObj;
}
}
启动后访问 swagger-ui.html 显示如下：
到目前为止已经满足基本的接口文档需求了、Example Value显示的内容根据RespObj
public class RespObj 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("");
sb.append("返回Ret状态码 ");
int i=1;
for (ResultEnum resultEnum : ResultEnum.values()) {
if(i%6==1){
sb.append("");
}
sb.append("");
sb.append(resultEnum.getCode());
sb.append(" ");
sb.append("");
sb.append(resultEnum.getMsg());
sb.append(" ");
if(i%6==0){
sb.append(" ");
}
i++;
}
sb.append("
");
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 {
到此为止，已经能够替换掉我们之前写的接口文档了。