文章目录


SpringBoot 集成 Swagger 生成 API 文档

有好处也有坏处,想要完整的表达出接口的所有详细信息,则接口上必须写大量的 swagger 注解来说明

相关依赖

<!-- swagger2 -->
<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>

配置类

/**
* 接口文档
*
* @author Tellsea
* @date 2019/7/13
*/
@EnableSwagger2
@Configuration
public class SwaggerConfig {

/**
* 定义分隔符
*/
private static final String SPLITOR = ";";

@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(basePackage("com.zyxx.common.controller".concat(SPLITOR).concat("")))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Skeleton API")
.description("来自懒惰小海绵")
.version("1.0")
.contact(new Contact("Tellsea", "https://github.com/Tellsea", )
.build();
}

public static Predicate<RequestHandler> basePackage(final String basePackage) {
return input -> declaringClass(input).transform(handlerPackage(basePackage)).or(true);
}

private static Function<Class<?>, Boolean> handlerPackage(final String basePackage) {
return input -> {
// 循环判断匹配
for (String strPackage : basePackage.split(SPLITOR)) {
boolean isMatch = input.getPackage().getName().startsWith(strPackage);
if (isMatch) {
return true;
}
}
return false;
};
}

private static Optional<? extends Class<?>> declaringClass(RequestHandler input) {
return Optional.fromNullable(input.declaringClass());
}
}

访问接口文档地址

浏览器直接访问:http://localhost:8080/swagger-ui.html

注意自己的端口和地址

更多注解说明

@Api

用在Controller中,标记一个Controller作为swagger的文档资源

属性名称

说明

value

Controller的注解

description(2.9 过时了)

对api资源的描述

hidden

配置为true 将在文档中隐藏

使用方法:

@Api(value = "用户控制器")
@Controller
@RequestMapping("userInfo")
public class UserInfoController extends BaseController<UserInfo> {
}

@ApiOperation

该注解用在Controller的方法中,用于注解接口

属性名称

说明

value

接口的名称

notes

接口的注释

response

接口的返回类型,比如说:response = String.class

hidden

配置为true 将在文档中隐藏

使用方法:

@ApiOperation(value = "新增用户", notes = "用户信息不能全为空", response = ResponseResult.class)
@PostMapping("saveUserInfo")
@ResponseBody
public ResponseResult saveUserInfo(UserInfo userInfo) {
baseService.insertSelective(userInfo);
return ResponseResult.build(StatusEnums.SAVE_SUCCESS);
}

@ApiParam

该注解用在方法的参数中

属性名称

说明

name

参数名称

value

参数值

required

是否必须,默认false

defaultValue

参数默认值

type

参数类型

hidden

隐藏该参数

使用方法:

public ResponseResult saveUserInfo(@ApiParam(name = "userInfo", value = "实体类UserInfo", required = true) UserInfo userInfo) {

}

@ApiResponses/@ApiResponse

该注解用在Controller的方法中,用于注解方法的返回状态

属性名称

说明

code

http的状态码

message

状态的描述信息

response

状态相应,默认响应类 Void

使用方法:

@ApiResponses({
@ApiResponse(code = 200, message = "保存成功"),
@ApiResponse(code = 401, message = "未授权!"),
@ApiResponse(code = 404, message = "参数未找到!"),
@ApiResponse(code = 403, message = "出错了!")
})
public ResponseResult saveUserInfo(UserInfo userInfo) {

}

@ApiModel

该注解用在实体类中

属性名称

说明

value

实体类名称

description

实体类描述

parent

集成的父类,默认为Void.class

subTypes

子类,默认为{}

reference

依赖,默认为“”

使用方法:

@ApiModel(value = "userInfo", description = "用户信息实体类")
public class UserInfo extends BaseEntity {

@ApiImplicitParams/ApiImplicitParam

该注解用在Controller的方法中,同ApiParam的作用相同,但是比较建议使用ApiParam。

属性名称

说明

name

参数名称

value

参数值

defaultValue

参数默认值

required

是否必须

allowMultiple

是否允许重复

dataType

数据类型

paramType

参数类型

@ApiImplicitParam(name = "userInfo", value = "用户信息实体类")
public ResponseResult saveUserInfo(UserInfo userInfo) {

}

@ApiModelProperty

该注解用在实体类的字段中

属性名称

说明

name

属性名称

value

属性值

notes

属性注释

dataType

数据类型,默认为“”

required

是否必须,默认为false

hidden

是否隐藏该字段,默认为false

readOnly

是否只读,默认false

reference

依赖,,默认“”

allowEmptyValue

是否允许空值,默认为false

allowableValues

允许值,默认为“”

使用方法:

/**
* 用户名
*/
@ApiModelProperty(name = "userName", value = "用户名", notes = "用户的登录账户")
private String userName;

技术分享区

【SpringBoot学习】29、SpringBoot 集成 Swagger 生成 API 文档_spring