Swagger

Swagger的简单使用

零、使用

一、添加 maven 依赖

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

截止2019年8月,当前最新的稳定版本就是 2.9.2

二、添加配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2);
        docket
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(this.infoApi().build());
        return docket;
    }

    /**
     * 文档信息配置
     */
    private ApiInfoBuilder infoApi() {
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();

        apiInfoBuilder.title("Swagger 文档");
        apiInfoBuilder.description("Swagger 文档 描述");
        apiInfoBuilder.version("1.0");

        return apiInfoBuilder;
    }
}

三、启动项目

启动项目,访问 http://{path}:{port}/swagger-ui.html 即可查看controller中的接口信息

一、配置

一、文档描述

在之前配置的 SwaggerConfig 中,我们可以配置整个文档的描述

     /**
     * 文档信息配置
     */
    private ApiInfoBuilder infoApi() {
        ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
        //标题
        apiInfoBuilder.title("Swagger 文档");
        //文档描述
        apiInfoBuilder.description("Swagger 文档 描述");
        //服务条款网址
        apiInfoBuilder.termsOfServiceUrl("https://maoyanting.com");
        //联系方式
        apiInfoBuilder.contact(new Contact("sandao","https://maoyanting.com","fhmaoyanting@163.com"));
        //开源协议
        apiInfoBuilder.license("MIT 协议");
        //开源协议地址
        apiInfoBuilder.licenseUrl("http://www.opensource.org/licenses/MIT");
        //版本号
        apiInfoBuilder.version("1.0");

        return apiInfoBuilder;
    }

二、类描述

使用 @Api 注解

@Api("用户相关接口")
@RestController()
public class UserController {}

@Api 主要属性

注解属性 类型 描述
value String 接口说明
tags Stirng[] 标签。
produces String 接口返回方式
consumes String 接口请求方式
Authorization Authorization[] 权限
protocols String 可用协议
hidden boolean 是否隐藏

三、方法描述

使用 @ApiOperation 注解

    @GetMapping("/testValid")
    @ApiOperation("校验用户接口")
    public String testValid(@Valid User user, BindingResult bindingResult){
    }

@ApiOperation 主要属性

注解属性 类型 描述
value String 接口说明。
notes String 操作的详细描述
tags Stirng[] 标签,可用于按资源或任何其他限定符对操作进行分组
response Class<?> 接口返回类型。
httpMethod String 接口请求方式。通常为 “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”.

四、参数描述

@ApiModel 设置实体类的描述。

@ApiModelProperty 设置实体类属性的描述

@Data
@ApiModel
public class User {
    @NotNull
    @ApiModelProperty("姓名")
    private String name;
    private String sex;
    private Integer age;
    private CareerEnum career;
    private List<User> children;
    }

@ApiModelProperty 主要属性

注解属性 类型 描述
value String 字段说明。
name String 重写字段名称。
dataType Stirng 重写字段类型。
required boolean 是否必填。
example Stirng 举例说明。
hidden boolean 是否在文档中隐藏该字段。
allowEmptyValue boolean 是否允许为空。
allowableValues String 该字段允许的值,当我们 API 的某个参数为枚举类型时,使用这个属性就可以清楚地告诉 API 使用者该参数所能允许传入的值。