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 {

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