Swagger 简介
Swagger
是一款用于生成、描述、调用和可视化 RESTful 风格的 Web 服务接口文档的框架。其最大的特点莫过于可以使接口文档与代码实时同步。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。
基于springBoot使用Swagger的应用流程
1、pom.xml 文件中引用相关依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2、编写 Swagger2 配置类
@Configuration
@EnableSwagger2
public class Swagger2Config {
@Bean
public Docket createDocket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.groupName("渔火照月光")
.enable(true)
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfo
(
"Api Documentation",
"Description Api Documentation",
"version 1.0.0",
"termsOfServiceUrl",
DEFAULT_CONTACT,
"License Apache 2.0",
"LicenseUrl http://www.apache.org/licenses/LICENSE-2.0",
new ArrayList<>()
);
}
}
apiInfo()
// Docket类中 apiInfo()方法,设置 API 接口文档信息,并返回 Docket 对象。
public Docket apiInfo(ApiInfo apiInfo)
// ApiInfo类的构造方法
public ApiInfo(String title, String description, String version, String termsOfServiceUrl, Contact contact,
String license, String licenseUrl, Collection<VendorExtension> vendorExtensions)
// Contact类的构造方法,设置 author 的 name、Website、Email
public Contact(String name, String url, String email)
groupName()
// groupName()设置分组名称
public Docket groupName(String groupName) {
this.groupName = (String)BuilderDefaults.defaultIfAbsent(groupName, this.groupName);
return this;
}
enable()
// 通过 enable 属性,在 application-{profile}.properties/yml 文件中设置相应值,控制在生产环境中不生成接口文档。
public Docket enable(boolean externallyConfiguredFlag)
select()
public ApiSelectorBuilder select() {
return new ApiSelectorBuilder(this);
}
apis()
// ApiSelectorBuilder类中 apis()方法,选择性扫描代码块 生成 API 接口文档
// apis(RequestHandlerSelectors.withClassAnnotation(RestController.class)) 扫描被 @RestController 修饰的类下的所有方法。
// apis(RequestHandlerSelectors.any())
// apis(RequestHandlerSelectors.none())
// apis(RequestHandlerSelectors.basePackage("com.welljoint.controller"))
// apis(RequestHandlerSelectors.withMethodAnnotation(RequestMapping.class))
public ApiSelectorBuilder apis(Predicate<RequestHandler> selector) {
this.requestHandlerSelector = Predicates.and(this.requestHandlerSelector, selector);
return this;
}
paths()
// paths(PathSelectors.any())
// paths(PathSelectors.none())
// paths(PathSelectors.regex(String pathRegex)) 通过正则表达式来匹配请求;
// paths(PathSelectors.ant(String antPattern)) 只扫描指定的路径下的请求。
public ApiSelectorBuilder paths(Predicate<String> selector) {
this.pathSelector = Predicates.and(this.pathSelector, selector);
return this;
}
build()
public Docket build()
3、Swagger2 重要注解介绍
@Api
:标记到类上
value
:在UI
界面上不显示该值tags
:类的详细描述
@ApiOperation
:标记到方法上
value
:接口名称notes
: 接口的详细描述
@ApiImplicitParams
:在请求的方法上,表示一组参数说明 。
@ApiImplicitParam
:在@ApiImplicitParams
注解中,指定一个参数说明。
name
:参数的名称value
:参数的描述required
:参数是否必须传dataType
:参数类型defaultValue
:参数的默认值paramType
:参数位置header
对应注解:@RequestHeader
query
对应注解:@RequestParam
path
对应注解:@PathVariable
body
对应注解:@requestbody
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "用户ID", required = true),
@ApiImplicitParam(name = "status", value = "用户状态", required = true)
})
@ApiResponses
:表示一组响应。
@ApiResponse
:在@ApiResponses
中,一般用于表达一个错误的响应信息。
code
:状态码message
:返回的自定义信息response
:抛出异常的类
@ApiModel
:标记到实体类上
@ApiModelProperty
:在实体类的属性上,描述属性。
4、访问文档
Swagger2
文档的默认地址是/swagger-ui.html