用 Swagger 测试任务分配问题中的 API

2024-01-05 12:32:46

一 Swagger2 介绍

1 什么是swagger2

编写和维护接口文档是每个程序员的职责，根据 Swagger2 可以快速帮助我们编写最新的 API 接口文档，再也不用担心开会前仍忙于整理各种资料了，间接提升了团队开发的沟通效率。

2 常用注解

swagger 通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等。

@Api：修饰整个类，描述 Controller 的作用
@ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述
@ApiModel：用对象来接收参数
@ApiModelProperty：用对象接收参数时，描述对象的一个字段
@ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

二 Swagger2 集成

1 项目整合 Swagger2

在 common 模块 pom.xml 引入依赖

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

说明：在 sdgt-parent 中的 pom.xml 中添加了版本控制，这里不需要添加版本。

2 添加 swagger2 配置类

在 service-util 模块添加配置类

/**
* @className: Swagger2Config
* @description: Swagger2配置信息
* @date: 2021/10/4
* @author: cakin
*/
@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket webApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("webApi")
                .apiInfo(webApiInfo())
                .select()
                // 只显示api路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/api/.*")))
                .build();
    }

    @Bean
    public Docket adminApiConfig() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("adminApi")
                .apiInfo(adminApiInfo())
                .select()
                // 只显示 admin 路径下的页面
                .paths(Predicates.and(PathSelectors.regex("/admin/.*")))
                .build();
    }

    private ApiInfo webApiInfo() {
        return new ApiInfoBuilder()
                .title("网站-API文档")
                .description("本文档描述了网站微服务接口定义")
                .version("1.0")
                .contact(new Contact("baiyee", "http://www.baiyee.cn/", "798103175@qq.com"))
                .build();
    }

    private ApiInfo adminApiInfo() {
        return new ApiInfoBuilder()
                .title("后台管理系统-API文档")
                .description("本文档描述了后台管理系统微服务接口定义")
                .version("1.0")
                .contact(new Contact("baiyee", "http://www.baiyee.cn/", "798103175@qq.com"))
                .build();
    }
}

3 给控制器加上 swagger 的注解

// 查询医院所有信息
@ApiOperation(value = "获取所有医院")
@GetMapping("findAll")
public Result findAllHospitalSet() {
    // 调用 service 的方法
    List<Hospital> list = hospitalService.list();
    return Result.ok(list);
}


// 逻辑删除医院
@ApiOperation(value = "逻辑删除医院")
@DeleteMapping("{id}")
public Result removeHospSet(@PathVariable String id) {
    boolean flag = hospitalService.removeById(id);
    if (flag) {
        return Result.ok();
    } else {
        return Result.fail();
    }
}