Swagger2使用
一、引入pom依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
二、编写配置类
package com.hi.test.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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;
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.hi.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger2")
.description("测试")
.termsOfServiceUrl("http://localhost:9999/doc.html")
.contact(new Contact("hhy","",""))
.version("1.0")
.build();
}
}
三、注解及说明
1、@Api 用在controller上
@Api 属性
属性名称 | 说明 |
---|
tags | 说明该类的作用,如果设置这个值、value的值会被覆盖 |
value | url的路径值,该参数没什么意义,所以不需要配置 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
2、用在方法上
注解 | 说明 |
---|
@ApiOperation | 用在请求的方法上,说明方法的作用,使用方式 |
@ApiImplicitParams | 用在方法上包含一组参数说明,里面包含@ApiImplicitParam注解 |
@ApiImplicitParam | 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明 |
@ApiResponses | 方法返回对象的说明 |
@ApiResponse | 用在 @ApiResponses里边 |
@ApiIgnore | 当作用在方法上时,方法将被忽略;作用在类上时,整个类都会被忽略;作用在参数上时,单个具体的参数会被忽略。(不会在接口文档显示) |
@ApiParam | 作用于方法的入参 |
1、@ApiOperation与Controller中的方法并列使用。
2、@ApiImplicitParams属性
属性名称 | 说明 |
---|
name | 参数名 |
value | 参数的说明、描述 |
required | 参数是否必须必填 |
dataType | 参数类型,默认String,其它值dataType=“Integer” |
defaultValue | 参数的默认值 |
paramType | 参数放在哪个地方 |
3、@ApiParam属性
属性 | 功能说明 |
---|
name | 名称 |
value | 简单描述 |
defaultValue | 参数值默认值 |
allowableValues | 可接收参数限制 |
required | 是否为必传参数 |
access | 参数过滤 |
allowMultiple | 指定参数是否可以通过多次出现来接收多个值 |
hidden | 隐藏参数列表中的参数 |
example | 非请求体(body)类型的单个参数示例 |
examples | 参数示例,仅适用于请求体类型的请求 |
4、@ApiResponse属性
属性名称 | 说明 |
---|
code | 状态码、数字,例如400 |
message | 信息 |
response | 抛出异常的类 |
3、@ApiModel:用于JavaBean上面,表示对JavaBean 的功能描述
@ApiModel属性
属性 | 功能说明 |
---|
value | 值 |
description | 描述 |
@ApiModelProperty属性
属性 | 功能说明 |
---|
value | 字段说明 |
name | 重写属性名字 |
dataType | 重写属性类型 |
required | 是否必须(默认false) |
example | 举例说明 |
hidden | 隐藏 |