文章目录
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", "[email protected]"))
.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;
技术分享区
