Swagger

Wed, Aug 21, 2019

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 使用者该参数所能允许传入的值。