Swagger的使用配置（一）

本文为swagger-ui的使用配置说明

pom的依赖：

<dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<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>

依赖说明：

springfox-swagger-ui 将swagger用ui的形式展示出来，否则只能在http://ip:port/v2/api-docs路径下展示出来

常用Swagger注解使用说明：

@Api(tags="") -- 类上注解，用于说明类
@ApiOperation("") -- 方法上的注解，用于说明方法，如果不指定默认是value值
@ApiIgnore -- 方法上使用默认不展示被注解了的方法
@ApiModel -- 类上用于说明对象类
@ApiModelProperty -- 对象类上的属性描述（多用于接口参数说明）

@ApiResponses -- 类上的注解，表示一组响应
@ApiResponse -- 在@ApiResponses内使用，表示一个错误信息的使用

eg：@ApiResponses({@ApiResponse(code=500, message = "内部错误", response = MessageReturn.class)})，其中：

code：错误码

message ：错误信息描述

response ：错误返回信息的类型

@ApiImplicitParams -- 多用在方法上，指定一组请求参数的各个方面
@ApiImplicitParam -- 在@ApiImplicitParams内使用，指定一个请求参数的各个方面

eg:@ApiImplicitParams({@ApiImplicitParam(paramType="query", name = "id", value = "主键ID", required = true, dataType = "Long")})

paramType：参数放在那个地方

header：请求参数的获取：@RequestHeader

query：请求参数的获取：@RequestParam

path：请求路径中参数的获取：@PathVariable

body：（不常用）

form：（不常用）

name：参数的名称

value：参数的描述

dataType ：参数的类型

defaultValue ：参数的默认值

required ：是否必填项

使用示例：

@Api(tags="用户相关接口")
@RestController
@RequestMapping("/test/info")
public class InfoController {

    @Autowired
    public InfoService infoService;

    @ApiOperation("获取所有用户信息", notes = "方法描述")//默认是value
    @GetMapping("/find")
    public List<Info> findAll(){
        return infoService.list();
    }

    @ApiIgnore
    @ApiOperation("获取详细信息")
    @GetMapping("/detail")
    public Info detail(Long id){
        return infoService.getById(id);
    }
  
    @ApiOperation("删除详细信息")
    @DeleteMapping("/delete")
    public void deleted(Long id){
        this.infoService.removeById(id);
    }
}

标准版：

SwaggerConfig的配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("测试swagger2使用")
                .contact(new Contact("XXX","http://localhost","123@456"))
                .version("1.0")
                .build();
    }
}

其中:

@Configuration ---- 告诉 Spring Boot 需要加载这个配置类
@EnableSwagger2 ---- 启用 Swagger2
Springfox 提供了一个 Docket 对象，让我们可以灵活的配置 Swagger 的各项属性
通过创建一个 ApiInfo 对象，并且使用 Docket.appInfo() 方法来设置文档信息的描述

优化版：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("xx.flower"))
                .paths(Predicates.or(PathSelectors.ant("/test/info/find"),
                        PathSelectors.ant("/test/info/delete")))//接口文档将只会展示 /test/info/find 和 /test/info/delete两个接口。
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("测试swagger2使用")
                .description("Swagger测试API描述")//加则展示，不加不展示描述信息
                .contact(new Contact("XXX","http://localhost","123@456"))
                .version("1.0")
                .build();
    }
}

其中:

apis() ：这种方式我们可以通过指定包名的方式，让 Swagger 只去某些包下面扫描
paths() ：这种方式可以通过筛选 API 的 url 来进行过滤

Swagger UI如下：

swagger-ui的展示界面

参考文献：

https://developer.ibm.com/zh/articles/j-using-swagger-in-a-spring-boot-project/
https://www.cnblogs.com/heroinss/p/9947978.html