1 环境
JDK1.8
Tomcat 8.0.39
Spring 4.3.9.RELEASE
已完成项目
2 Swagger2的maven依赖
在项目根pom.xml中引入jar及其版本号。
<!-- 构建Restful API -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>
在根pom.xml中,设置版本号。如图2-a
图2-a
在根pom.xml中,引入jar包及版本。如图2-b
图2-b
在项目的核心包中的pom.xml中引入jar。如图2-c
图2-c
3 Swagger配置类
在项目中创建 一个类名为RestApiConfig的Swagger配置文件
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
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;
@EnableWebMvc
@EnableSwagger2
@Configuration
@ComponentScan(basePackages ="com.hw.one.core.controller")
public class RestApiConfig extends WebMvcConfigurationSupport {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.host("localhost:8080/api")
.protocols(Sets.newHashSet("https","http"))
//.pathMapping("/")
.select()
//只生成被Api这个注解注解过的类接口 //.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
//只生成被ApiOperation这个注解注解过的api接口
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//生成所有API接口 //.apis(RequestHandlerSelectors.basePackage("com.hw.one.core.controller"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("ONE基础平台API")
.description("ONE基础平台在线API文档,主要提供基础平台的所有功能实现接口。")
// .license("稳定版")
// .termsOfServiceUrl("http://localhost:8080/dist/index.html")
// .contact(new Contact("ONE基础平台","http://192.168.15.246:8025/#/login","scsoft@163.com"))
.version("2.0.0")
.build();
}
}
4 Swagger-UI配置
Swagger扫描解析得到的是一个json文档,对于用户不太友好。下面介绍swagger-ui,它能够友好的展示解析得到的接口说明内容。
从https://github.com/swagger-api/swagger-ui 获取其所有的 dist 目录下东西放到需要集成的项目里,本文放入one-web/one-swagger 目录下。如图4-1-a
图4-1-a
修改dist/index.html文件,默认是从连接
http://petstore.swagger.io/v2/swagger.json获取 API 的 JSON,这里需要将url值修改为http://{ip}:{port}/{projectName}/api-docs的形式,{}中的值根据自身情况填写。
比如我的url值:http://localhost:8080/s/v2/api-docs 如图4-1-b
图4-1-b
Web.xml中过滤器的配置.如图4-1-c
图4-1-c
如果有认证,则不认证url前缀为v2/api-docs 。如图4-1-d
图4-1-d
页面访问地址:localhost:8080/dist/index.html . 如图4-1-e
图4-1-e
5 Controller类配置
5.1 类的注解配置
通过对类的注解,来规定类的特征。如图:5-1
图5-1
5.2 类注解属性说明
1. @Api:修饰整个类,描述Controller的作用,其各属性作用:
属性名称 | 属性特性描述 |
value | 类概要描述 |
tags | 用于资源或任何其他限定符的逻辑分组。如果设置这个值、value的值会被覆盖 |
description | 对类的详细描述。 |
basePath | 基本路径可以不配置。 |
position | 如果配置多个Api 想改变显示的顺序位置。(已过时) |
produces | 响应类型定义属性:"application/json, application/xml"。 |
consumes | 请求类型定义属性"application/json, application/xml"。 |
protocols | 定义类所使用的协议: http, https, ws, wss。 |
authorizations | 高级特性认证时配置。 |
hidden | 配置为true 将在文档中隐藏该方法。 |
response | 操作相应类型。 |
responseContainer | 声明一个响应容器,可以是 "List", "Set" or "Map",其他无效。 |
httpMethod | 请求类型:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" , "PATCH"。 |
code | http的状态码 默认 200。 |
extensions | 扩展属性。 |
类注解在本项目中主要使用如下:
@Api() -用于类,表示标识这个类是swagger的资源 。
tags–表示说明 ,可以标识为类名。
value–也是说明,可以使用tags替代 tags。
description-对类的描述。(已过时)
如图5-2-a所示
图5-2-a
通过类的注解,swagger ui显示的效果图。如图5-2-b;
图5-2-b
5.3 方法注解的配置
通过对方法的注解,来规定方法的特征。如图5-3
图5-3
上述代码是Controller中的一个方法,@ApiOperation注解对这个方法进行了说明,@ApiOperation:注解方法,value为简要描述,notes为全面描述,hidden=true Swagger将不显示该方法,默认为false。
@ApiParam注解对方法参数进行了说明。
注:忽略某个接口类,需要注解@ApiIgnore
@ApiIgnore:注解类、参数、方法,注解后将不在Swagger UI中显示。如图5-3-a
图5-3-a
5.4 方法注解属性说明
1.@ApiOperation注解:用在方法上,说明方法的作用,其中各属性的含义:
属性名称 | 属性特性描述 |
value | 方法概要描述 |
tags | 用于资源或任何其他限定符的逻辑分组。使用时,覆盖value值。 |
description | 对方法的详细描述。 |
basePath | 基本路径可以不配置。 |
position | 如果配置多个Api 想改变显示的顺序位置,(已过时)。 |
produces | 响应类型定义属性:"application/json, application/xml"。 |
consumes | 请求类型定义属性"application/json, application/xml"。 |
protocols | 定义方法所使用的协议: http, https, ws, wss。 |
authorizations | 高级特性认证时配置。 |
hidden | 配置为true 将在文档中隐藏该方法。 |
response | 操作相应类型。 |
responseContainer | 声明一个响应容器,可以是 "List", "Set" or "Map",其他无效。 |
httpMethod | 请求类型:"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" , "PATCH"。 |
code | http的状态码 默认 200。 |
extensions | 扩展属性。 |
方法注解在本项目中主要使用如下:
@ApiOperation -用于方法说明,表示标识这个方法是swagger的资源 。
value用于方法描述
notes用于方法的详细描述
如图5-4-a所示
图5-4-a
通过类的注解,swagger ui显示的效果图。如图5-4-b;
图5-4-b
2. @ApiImplicitParam的参数说明:
属性 | 取值 | 属性特性描述 |
paramType |
| 查询参数类型 |
| path | 以地址的形式提交数据,(用于restful接口)-->请求参数的获取:@PathVariable。 |
| query
| 请求参数放置于请求地址。(可以直接使用@RequestParam获取。) |
| body | 以流的形式提交 仅支持POST。 |
header | 请求参数放置于Request Header。(可以直接使用@RequestHeader获取。) | |
form | 以form表单的形式提交 仅支持POST。 | |
dataType |
| 参数的数据类型 只作为标志说明,并没有实际验证。 |
| Long |
|
| String |
|
name |
| 接收参数名 |
value |
| 接收参数的意义描述 |
required |
| 参数是否必填 |
| true | 必填 |
| false | 非必填 |
defaultValue |
| 默认值 |
方法参数注解在本项目中主要使用如下:
@ApiImplicitParam() 用于方法 ,表示单独的请求参数
@ApiImplicitParams() 用于方法,包含多个 @ApiImplicitParam
name–参数名
value–参数说明
dataType–数据类型
paramType–参数类型
example–举例说明
如图5-4-c
图5-4-c
通过类的注解,swagger ui显示的效果图。如图5-4-c;
图5-4-c
3. @ApiParam注解 (本项目暂时未用)
@ApiParam请求属性,使用方式:
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true) User user)
属性名称 | 属性特性描述 |
name | 属性名称 |
value | 属性值 |
defaultValue | 默认属性值 |
allowableValues | 可以不配置 |
required | 是否属性必填 |
access | 不过多描述 |
allowMultiple | 默认为false |
hidden | 隐藏该属性 |
example | 举例子 |
4. @ApiResponse注解(本项目暂时未用)
@ApiResponse:响应配置,使用方式:
@RequestMapping(value = "/order", method = POST)
@ApiOperation(value = "Place an order for a pet", response = Order.class)
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
属性配置:
属性名称 | 属性特性描述 |
code | http的状态码 |
message | 描述 |
response | 默认响应类 Void |
reference | 参考ApiOperation中配置 |
responseHeaders | 参考 ResponseHeader 属性配置说明 |
responseContainer | 参考ApiOperation中配置 |
5. @ApiResponses注解 (本项目暂时未用)
@ApiResponses:响应集配置,使用方式:
@RequestMapping(value = "/order", method = POST)
@ApiOperation(value = "Place an order for a pet", response = Order.class)
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })
6. @ResponseHeader注解 (本项目暂时未用)
@ResponseHeader响应头设置,使用方法
@ResponseHeader(name="head1",description="response head conf")
属性名称 | 描述 |
name | 响应头名称 |
description | 头描述 |
response | 默认响应类 Void |
responseContainer | 参考ApiOperation中配置 |
7.其他 (本项目暂时未用)
@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候;
@ApiModelProperty:描述一个model的属性。