Java-swagger

效果图 :

环境配置 :
1> pom.xml :

<!-- Swagger 如果为Integer类型,不给example默认值则会报NumberFormatException-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>
<!-- 解决方案 使用1.5.21版本-->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
	<exclusions>
		<exclusion>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-annotations</artifactId>
		</exclusion>
		<exclusion>
			<groupId>io.swagger</groupId>
			<artifactId>swagger-models</artifactId>
		</exclusion>
	</exclusions>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>
<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-annotations</artifactId>
	<version>1.5.21</version>
</dependency>
<dependency>
	<groupId>io.swagger</groupId>
	<artifactId>swagger-models</artifactId>
	<version>1.5.21</version>
</dependency>

<!-- swagger-bootstrap-ui --> 
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>1.9.3</version>
</dependency>

2> application.properties :

# 需要swagger扫描的包
swagger.basepackage=
# 项目分组
swagger.group=
# 项目标题
swagger.title=
# 项目描述
swagger.description=
# 项目版本
swagger.version=1.0.0
# 服务访问地址
swagger.termsOfServiceUrl=
# 联系人
swagger.contact=urn:tos
# 根路径
swagger.basepath=/v1
swagger.license=LICENSE-2.0
swagger.licenseUrl=http://www.apache.org/licenses/LICENSE-2.0
# 是否展示
swagger.show=true

3> 项目配置 SwaggerConfig.java

import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.context.request.async.DeferredResult;
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;

/**
 * swagger配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
	@Value("${swagger.group:bigtreefinance}")
	private String group;
	@Value("${swagger.title:未设置项目标题}")
	private String title;
	@Value("${swagger.description:未设置项目描述}")
	private String description;
	@Value("${swagger.version:未设置版本号}")
	private String version;
	@Value("${swagger.termsOfServiceUrl:未设置服务地址}")
	private String termsOfServiceUrl;
	@Value("${swagger.contact:未设置联系人}")
	private String contact;
	// 可以取server.servlet.context-path
	@Value("${swagger.basepath:/}")
	private String basepath;
	@Value("${swagger.basepackage:com}")
	private String basepackage;
	@Value("${swagger.show:true}")
	private String show;
	
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.enable(show)
				.genericModelSubstitutes(DeferredResult.class)
				.useDefaultResponseMessages(false)
				.forCodeGeneration(false)
				.pathMapping(basepath)
				.select()
				.apis(RequestHandlerSelectors.basePackage(basepackage))
				.build()
				.apiInfo(productApiInfo());
	}
	
	private ApiInfo productApiInfo() {
		ApiInfo apiInfo = new ApiInfo(title, description, version, termsOfServiceUrl, contact, "LICENSE-2.0", "http://www.apache.org/licenses/LICENSE-2.0");
		return apiInfo;
	}
}

5> 配置过滤器

/doc.html,/v2/api-docs,/v2/api-docs-ext,/webjars/**,/swagger-resources

6> swagger注解相关

   @RestController
   /**
    * produces : For example, "application/json, application/xml"  , 可选
    * consumes : For example, "application/json, application/xml"  , 可选
    * tags     : 类接口所属业务[正常应与此类下的接口方法配置一致],接口文档会依据tags进行分组展示 , 必填
   */
   @Api(produces = "application/json",consumes = "application/json",tags = "订单服务")
   public class SwaggerWeb {
	private static final String TAGS = "订单服务";
	
	/**
	  *  订单新增 : 传递实体Bean通过@ApiParam进行注解
	  *  注解说明 : 参考订单查询
	 */
	@ApiOperation(tags = TAGS, value = "订单新增", notes = "订单新增:新增订单接口", hidden = false, response = ResponseEntity.class)
	@PostMapping(value = "/order")
	/**
	 * @ApiParam 作用与实体Bean,无需配置name和value.会依据实体Bean配置进行注解.
	 * hidden : 是否隐藏参数
	 * required : 是否必填
	 */
	public ResponseEntity add(@ApiParam(hidden = false,required = false) @RequestBody @Valid ReqEntity reqEntity) {
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(reqEntity.toString()));
	}
	
	/**
	  * 订单删除 : 传递非实体Bean使用@ApiImplicitParams进行注解
	  * 注解说明 : 参考订单查询
	 */
	@ApiOperation(tags = TAGS, value = "订单删除", notes = "订单删除:通过自增ID删除订单.", hidden = false, response = ResponseEntity.class)
	@ApiImplicitParams({
		/**
		  * 注解说明 : 参考订单查询
		 */
		@ApiImplicitParam(name = "id", value = "自增ID", example = "1",required = true)
	})
	@DeleteMapping(value = "/order/{id}")
	public ResponseEntity delete(@PathVariable("id") String id) {
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(id));
	}
	
	/**
	  *  订单修改 : 传递实体Bean与Path
	  *  注解说明 : 参考订单查询
	 */
	@ApiOperation(tags = TAGS, value = "订单修改", notes = "订单修改:通过自增ID进行修改", hidden = false, response = ResponseEntity.class)
	@ApiImplicitParams({
		/**
		  * 注解说明 : 参考订单查询
		 */
		@ApiImplicitParam(name = "id", value = "自增ID", example = "1",required = true)
	})
	@PostMapping(value = "/order/{id}")
	/**
	 * @ApiParam 作用与实体Bean,无需配置name和value.会依据实体Bean配置进行注解.
	 * hidden : 是否隐藏参数
	 * required : 是否必填
	 */
	public ResponseEntity update(@PathVariable("id") String id,@ApiParam(hidden = false,required = false) @RequestBody @Valid ReqEntity reqEntity) {
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(id,reqEntity.toString()));
	}
	
	/**
	  *  订单查询 : 传递非实体Bean使用@ApiImplicitParams进行注解
	 * tags : 接口所属业务组,接口文档会依据tags进行分组展示 , 如果与类的tags一致,可不填
	 * value : 接口名称 , 必填
	 * notes : 接口描述 , 可选
	 * hidden : 是否隐藏,默认false , 可选
	 * response : 返回的对象 , 必填
	 */
	@ApiOperation(tags = TAGS, value = "订单查询", notes = "订单查询:通过订单编号和订单名称进行查询", hidden = false, response = ResponseEntity.class)
	@ApiImplicitParams({
		/**
		 * name : 参数名称[需与方法中名称一致] , 必填
		 * vale : 参数说明 , 必填
		 * required : 是否必填 , 可选
		 * example : 样例 , 可选
		 */
		@ApiImplicitParam(name = "orderNo", value = "订单编号", example = "DDBH1130730655556190208",required = false),
		@ApiImplicitParam(name = "orderName", value = "订单名称", example = "销售单")
	})
	@GetMapping(value = "/order")
	public ResponseEntity get(String orderNo,String orderName) {
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(orderNo,orderName));
	}
	
	/**
	  *  文件上传
	  *  注解说明 : 参考订单查询
	 */
	@ApiOperation(tags = TAGS,value = "文件上传", notes = "文件上传[选择文件进行上传]",hidden = false,response = ResponseEntity.class)
	@ApiImplicitParams({
		/**
		  *  注解说明 : 参考订单查询
		 */
		@ApiImplicitParam(name = "col1",value = "字段1",example = "c1",required = true)
	})
	@PostMapping(value = "/file")
	public Object file(String col1,@ApiParam(value = "上传的文件",required = true)MultipartFile file
	) {
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(col1,file.getOriginalFilename()));
	}
	
	/**
	  *  传递list参数
	  *  注解说明 : 参考订单查询
	 */
	@ApiOperation(tags = TAGS,value = "list传参", notes = "传递List参数",hidden = false,response = ResponseEntity.class)
	@PostMapping(value = "/list")
	public Object list(@ApiParam(value = "订单列表",required = false) @RequestBody List<Integer> ids) {
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(ids.toString()));
	}

	/**
	  *  传递list实体类参数
	  *  注解说明 : 参考订单查询
	 */
	@ApiOperation(tags = TAGS,value = "list实体类传参", notes = "传递List实体类参数",hidden = false,response = ResponseEntity.class)
	@PostMapping(value = "/listBean")
	public Object listBean(@ApiParam(value = "实体Bean列表",required = false) @RequestBody List<ReqEntity> ids) {
		System.err.println(ids);
		return new ResponseEntity(200, "SUCCESS",Arrays.asList(ids.toString()));
	}
	
   }
   
   实体Bean swagger注解
   
   /**
    * value : Bean的Schemal,实体类首字母小写即可 , 必填
    * description : Bean描述信息 , 必填
    */
   @ApiModel(value = "RequestEntity",description = "订单实体类")
   public class ReqEntity {
	/**
	 * value : 参数说明 , 必填
	 * example : 样例, 当为Bean或者List<Bean>时无需填写 , 可选
	 * required : 是否必填 , 可选
	 * hidden : 是否隐藏参数,默认为false, 可选
	 */
	@ApiModelProperty(value = "姓名",required = true,example = "anyf",hidden = false)
	private String name;
	@ApiModelProperty(value = "年龄",example = "29")
	private Integer age;
	// 实体Bean无需写example,依据UserEntity的swagger进行配置
	@ApiModelProperty(value = "用户列表")
	private List<UserEntity> userEntitys;
	@ApiModelProperty(value = "用户信息")
	private UserEntity userEntity;
   }

   @ApiModel(value = "ResponseEntity",description = "响应参数")
   public class ResponseEntity {
	@ApiModelProperty(value = "响应码",required = true,example = "200")
	private Integer code;
	@ApiModelProperty(value = "响应描述",example = "SUCCESS")
	private String message;
	@ApiModelProperty(value = "响应数据")
	private Object data;
   }

7> 附录 : dataType 类型

int date string double float boolean byte object long date-time file biginteger bigdecimal

8> 补充说明

请求参数配置方式分两种 : 
第一种 :  
// 这种方式无法配置hidden
@ApiImplicitParams({ // 实体Bean无需配置
	@ApiImplicitParam(name = "col1",value = "字段1",example = "v1"),
	@ApiImplicitParam(name = "col2",value = "字段2",example = "v2",required = true),
	@ApiImplicitParam(name = "id",value = "唯一标识",required = true,example = "1")
})
@GetMapping(value = "/order/{id}")
public Object test1(
		String col1,String col2,
		@ApiParam(required = false,hidden = false) @RequestBody ReqEntity reqEntity,
		@PathVariable("id") String id
) {
	return new ResponseEntity(200, "SUCCESS",Arrays.asList(col1,col2,reqEntity.toString(),id));
}
第二种 : 
// 这种方式dataType为body类型,无法传递非实体Bean参数
public Object test1(
		@ApiParam(required = false,hidden = false,name="col1",value="字段1") String col1, // 报错
		String col2,
		@ApiParam(required = false,hidden = false) @RequestBody ReqEntity reqEntity // 可传
) {
	return new ResponseEntity(200, "SUCCESS",Arrays.asList(col1,col2,reqEntity.toString(),id));
}

访问地址 :

http://localhost:ip/doc.html