Swagger2接口测试使用
一款让你更好的书写API文档规范且完整的框架。
1导入第三方依赖
<!--swagger-->
<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>
2编写Swagger2的配置类
(放在启动类同级目录)
package com.jia;
//swagger2的配置文件,在项目的启动类的同级文件建立
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 {
//swagger2的配置文件,这里可以配置swagger2的一些基本的内容,比如扫描的包等等
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.jia.controller"))
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 测试使用 Swagger2 构建RESTful API")
//创建人
.contact(new Contact("MarryFeng", "http://www.jiazhibo.top", "1271421134"))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
访问地址: 域名:端口/swagger-ui.html
Api 标记一个Controller类做为swagger 文档资源
使用方式:
@Api(value = "/user", description = "Operations about user")
属性名称 | 备注 | 默认值 |
---|---|---|
value | url的路径值 | |
tags | 如果设置这个值、value的值会被覆盖 | |
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 将在文档中隐藏 |
ApiOperation 每一个url资源的定义
属性名称 | 备注 | 默认值 |
---|---|---|
value | url的路径值 | |
tags | 如果设置这个值、value的值会被覆盖 | |
notes | 对api资源的描述 | |
response | 返回的对象 | |
responseContainer | 这些对象是有效的 "List", "Set" or "Map".,其他无效 | |
responseReference | 可以不配置 | |
httpMethod | 可以接受 "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" | |
position | 如果配置多个Api 想改变显示的顺序位置 | |
produces | 同 Api中的定义 | |
consumes | 同 Api中的定义 | |
protocols | 同 Api中的定义 | |
authorizations | 同 Api中的定义 | |
hidden | 同 Api中的定义 | |
code | http的状态码 默认 200 | |
extensions | 扩展属性 |
ApiParam请求属性
属性名称 | 备注 | 默认值 |
---|---|---|
name | 属性名称 | |
value | 属性值 | |
defaultValue | 默认属性值 | |
allowableValues | 可以不配置 | |
required | 是否属性必填 | |
access | 不过多描述 | |
allowMultiple | 默认为false | |
hidden | 隐藏该属性 | |
example | 举例子 | |
examples |
ApiResponse响应配置
code | http的状态码 | |
---|---|---|
message | 描述 | |
response | 默认响应类 Void | |
reference | 参考ApiOperation中配置 | |
responseHeaders | 参考 ResponseHeader 属性配置说明 | |
responseContainer | 参考ApiOperation中配置 |
评论区