Swagger 常用注解

前言

通过代码和注释自动生成文档。在 Swagger 框架下，开发人员可对服务进行归类说明，对方法，模型，返回结果等进行详细说明。

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>3.0.0</version>
</dependency>

1、Swagger 常用注解

1.1、控制器层

1.1.1、@Api

@Api 注解用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。

@RestController
@RequestMapping("/yang")
@Api(tags = "人员信息 API", description = "提供人员信息相关的 Rest API")
public class UserController {
}

1.1.2、@ApiOperation

此注解提供了丰富的属性来允许我们自定义接口的描述信息，包括接口名称和所属分组等。

@ApiOperation(value = "人员查询接口", notes = "查询描述")
@RequestMapping(value = "/queryUser", method = RequestMethod.POST)
public int queryUser(@RequestBody Map<String, Object> map) throws Exception {
    return userIServiceImpl.queryUser(map);
}

1.1.3、@ApiImplicitParam

此注解只能标注在方法上，代表了方法中的一个独立的参数，如果方法有多个参数，可以和 @ApiImplicitParams 注解搭配使用。

1.1.4、@ApiImplicitParams

此注解是 @ApiImplicitParam 注解的包装器，单独使用没有意义，必须和 @ApiImplicitParam 进行搭配，当接口方法中有一个及以上的参数时可以使用。

@ApiImplicitParams({
    @ApiImplicitParam(name = "page", value = "当前页", required = false, dataType = "Integer"),
    @ApiImplicitParam(name = "pageSize", value = "每页显示条数", required = false, dataType = "Integer"),
    @ApiImplicitParam(name = "sort", value = "排序字段", required = false, dataType = "String")})
@RequestMapping(value = "/queryUser", method = RequestMethod.POST)
public int queryUser(@RequestBody Map<String, Object> map) throws Exception {
    return userIServiceImpl.queryUser(map);
}

1.1.5、@ApiResponses

@ApiResponses、@ApiResponse 进行方法返回对象的说明。

1.1.6、@ApiResponse

@ApiResponses、@ApiResponse 进行方法返回对象的说明。

@ApiResponses({
        @ApiResponse(code = 200, message = "请求成功"),
        @ApiResponse(code = 400, message = "请求参数没填好"),
        @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@RequestMapping(value = "/queryUser", method = RequestMethod.POST)
public int queryUser(@RequestBody Map<String, Object> map) throws Exception {
    return userIServiceImpl.queryUser(map);
}

1.2、实体层

1.2.1、@ApiModel

此注解是作用在接口相关的实体类上的注解，用来对该接口的相关实体类添加额外的描述信息，一般和 @ApiModelProperty 注解配合使用。

@Data
@ApiModel(description= "人员实体类")
public class User {
}

1.2.2、@ApiModelProperty

此注解可标注在方法或字段上，通常配合 @ApiModel 注解一起使用，用于添加或操作接口相关实体类的字段信息。

package com.example.test.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel(description= "人员实体类")
public class User {

    @ApiModelProperty(value = "姓名", required = true)
    private String name;

    @ApiModelProperty(value = "年龄", required = true)
    private Integer age;
}

2、文档

2.1、添加 SwaggerConfig

package com.example.test.entity;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2 // 开启Swagger2服务
public class SwaggerConfig {

    @Bean
    public Docket buildDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
            .apis(RequestHandlerSelectors.basePackage("com.example.test.controller"))// 此处的包路径需要修改为自己的
            .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
            .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("API在线文档") // 设置文档的标题
            .description("API在线文档描述") // 设置文档的描述
            .version("1.0.0") // 设置文档的版本信息
            .contact(new Contact("yang", "", "[email protected]")).termsOfServiceUrl("NO terms of service")
            .license("The Apache License")// 链接名称
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")// 链接地址
            .build();
    }
}

2.2、访问

http://localhost:1213/swagger-ui.html