keac's Bolg.

学习SpringBoot之整合 Swagger2

字数统计: 968阅读时长: 4 min
2019/07/24 Share

SpringBoot 整合 Swagger2

我写的Github 地址 SpringBoot+Swagger2 Github

我在使用的时候遇到一点很神奇的问题,SpringBoot 版本为 2.1.6.RELEASE的时候,就会报错,换到2.1.4.RELEASE的时候就正常了,很神奇。回头再研究下

加入依赖

1
2
3
4
5
6
7
8
9
10
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@Configuration
@EnableSwagger2
public class ApiConfig {

@Bean
public Docket docket() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.keac"))//扫描路径
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiImplicitParams.class))//根据注解定制
.paths(PathSelectors.any()) //定义哪些路径的接口需要生成文档
.build();
}
@Bean
public ApiInfo apiInfo() {
Contact contact = new Contact("sky","https://www.loongten.com","admin@wgpsec.org");
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful API")//文档首页标题
.description("swagger2-文档构建利器")//文档描述信息
.contact(contact) //创建者信息
.version("1.0") //文档版本
.build();
}
}

可以访问 http://localhost:8080/swagger-ui.html

访问成功

(来自网上的复制粘贴,记录下方便之后查询)

springfox的标签

@Api:修饰整个类,描述Controller的作用

@ApiOperation:描述一个类的一个方法,或者说一个接口

@ApiImplicitParams:多个请求参数

@ApiImplicitParam:一个请求参数

@ApiResponses:HTTP响应整体描述

@ApiResponse:HTTP响应其中1个描述

@ApiModel:用对象来接收参数

@ApiModelProperty:用对象接收参数时,描述对象的一个字段

@ApiIgnore:使用该注解忽略这个API

类和方法的描述

@Api修饰整个类,描述Controller的作用

@ApiOperation 贴在方法上,描述一个方法的作用

1) @Api注解的使用:贴在类上,主要用下面的这几个属性
1) value:该controller简短的标题
2) description:详细介绍
3) producer:说明该controller是使用什么显示层格式的
4) protocols:使用什么协议
2) @ApiOperation注解的使用:贴在方法上,主要用下面的这几个属性
1) value:该方法简短的变态
2) note:详细介绍
3)code:正常情况下返回的状态码是多少
4)httpMethod:使用什么http方法
5) response:响应什么对象,这里写的是响应的对象的字节码

参数的描述

贴在参数上

@ApiImplicitParams 多个请求参数

@ApiImplicitParam 一个请求参数

@ApiParam 单个参数描述

1) name:参数名
2) value:参数名对应的值
3) dataType:参数的类型
4) require:该参数是否必填
5) paramType:该参数的来源类型,它的值有如下:

query:该参数从地址栏问号后面的参数获取

form:该参数从form表单中获取

path:该参数从URL地址上获取

body:该参数从请求体中获取

header:该参数从请求头获取

响应的描述

@ApiResponses:HTTP响应整体的描述

@ApiResponse:HTTP响应中某一种响应的描述

用在@ApiResponses中,一般用于表达一个错误的响应信息(200相应不写在这里面)

code:数字,例如400

message:信息,例如”请求参数没填好”

response:抛出的异常类

对象模型描述

@ApiModel/@ApiModelProperty

@ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用

@ApiImplicitParam注解进行描述的时候)

@ApiModelProperty:描述一个model的属性

忽略接口API

@ApiIgnore 贴了该注解的api 会被忽略,不生成接口文档

两种不生成api的方式

1) @ApiIgnore:可以贴在类和方法上

2) 在swagger配置类上的select()方法上调用apis(),apis方法需要传入一个selector。可以使用RequestHandlerSelector内置的selector

CATALOG
  1. 1. SpringBoot 整合 Swagger2
    1. 1.1. 加入依赖
    2. 1.2. springfox的标签
      1. 1.2.1. 类和方法的描述
    3. 1.3. 参数的描述
      1. 1.3.1. 贴在参数上
      2. 1.3.2. 响应的描述
      3. 1.3.3. 对象模型描述
      4. 1.3.4. 忽略接口API
      5. 1.3.5. 两种不生成api的方式