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

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", "3210054449@qq.com"))
                .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;

技术分享区