技术分享 | Spring Boot 集成 Swagger

本文节选自霍格沃兹测试学院内部教材

Swagger UI 允许任何人（无论您是开发团队还是最终用户）都可以可视化 API 资源并与之交互，而无需任何实现逻辑。它是根据您的 OpenAPI（以前称为 Swagger）规范自动生成的，具有可视化文档，可简化后端实现和客户端使用。

为什么使用Swagger

• 自动生成文档：避免手写错误,只需少量注解，Swagger 就可以根据代码自动生成 API 文档，保证了文档的时效性；
• 跨语言性，支持 40 多种语言，Swagger 已经慢慢演变成了 OpenAPI 规范；
• Swagger UI 呈现出来的是一份可交互式的 API 文档，我们可以直接在文档页面尝试 API 的调用，省去了准备复杂的调用参数的过程；
• 对于某些没有前端界面 UI 的功能，可以用它来测试接口；
• 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位问题。

Swagger快速开始

引入依赖

这里选择 2.9.2 版本。

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

添加配置

添加配置类

添加一个 Swagger 配置类，在工程下新建 config 包并添加一个 SwaggerConfig 配置类。


SwaggerConfig.java


```java
import com.google.common.collect.Lists;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.ParameterBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.schema.ModelRef;
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
public class SwaggerConfig {


    //作为Springfox框架的主要接口的构建器,提供合理的默认值和方便的配置方法。
    @Bean
    public Docket docket() {


        ParameterBuilder builder = new ParameterBuilder();
        builder.parameterType("header").name("token")
                .description("token值")
                .required(true)
                .modelRef(new ModelRef("string")); // 在swagger里显示header


        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("aitest_interface")
                .apiInfo(apiInfo())
                .globalOperationParameters(Lists.newArrayList(builder.build()))
                .select().paths(PathSelectors.any()).build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("aitest-mini系统")
                .description("aitest-mini接口文档")
                .contact(new Contact("tlibn", "", "103@qq.com"))
                .version("1.0")
                .build();
    }


}
```

添加控制器

添加一个控制器，在工程下新建 controller包并添加一个Controller控制器，如果已经存在Controller控制器，则直接启动服务也可以，如上章我们编写了HogwartsTestUserController类，此时直接启动服务即可。

使用与测试

打开 swagger 接口文档界面

启动 Spring Boot 服务，打开浏览器，访问：http://127.0.0.1:8081/swagger-ui.html，进入swagger接口文档界面。

测试

展开 hogwarts-test-user-controller 的任意接口，输入参数并点击执行，就可以看到接口测试结果了。

Swagger 常用注解

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

Api：修饰整个类，描述 Controller 的作用

Api(tags = "霍格沃兹测试学院-用户管理模块", hidden = true)

ApiOperation：描述一个类的一个方法，或者说一个接口

ApiOperation("查询用户列表")

ApiParam：单个参数描述

ApiModel：用对象来接收参数

 ApiModel(value = "用户登录类", description = "请求类")

ApiProperty：用对象接收参数时，描述对象的一个字段

ApiModelProperty(value="用户id", example="1",required=true)

ApiResponse：HTTP 响应其中 1 个描述

ApiResponses：HTTP 响应整体描述

ApiIgnore：使用该注解忽略这个 API

ApiError ：发生错误返回的信息

ApiImplicitParam：一个请求参数

ApiImplicitParams：多个请求参数

更多参见 https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview

添加 Swagger 常用注解后的效果

添加 Swagger 常用注解后的示例代码

HogwartsTestUserController.java

@Api(tags = "霍格沃兹测试学院-用户管理模块", hidden = true)
@RestController
@RequestMapping("/api/user")
public class HogwartsTestUserController {


    /**
     * 查询用户列表，返回一个JSON数组
     * */
    @ApiOperation("查询用户列表")
    @GetMapping("/users")
    @ResponseStatus(HttpStatus.OK)
    public Object getUsers(){
        List<UserDto> list = getData();
        return list;
    }
获取更多相关资料：请添加vx,ceshiren001

    /**
     * 查询用户信息，返回一个新建的JSON对象
     * */
    @ApiOperation("查询用户信息")
    @GetMapping("/users/{id}")
    @ResponseStatus(HttpStatus.OK)
    public Object getUser(@PathVariable("id") Long id){


        if(Objects.isNull(id)){
            return null;
        }


        List<UserDto> list= getData();
        UserDto userDto = getUserDto(id, list);


        return userDto;
    }


    /**
     * 新增用户
     * */
    @ApiOperation("新增用户")
    @PostMapping("/users")
    @ResponseStatus(HttpStatus.CREATED)
    public Object addUser(@RequestBody UserDto user){


        List<UserDto> list= getData();
        list.add(user);//模拟向列表中增加数据
        return user;
    }


    /**
     * 编辑用户
     * */
    @ApiOperation("编辑用户")
    @PutMapping("/users/{id}")
    @ResponseStatus(HttpStatus.CREATED)
    public Object editUser(@PathVariable("id") Long id,@RequestBody UserDto user){
        List<UserDto> list = getData();
        for (UserDto userDto:list) {
            if(id.equals(userDto.getId())){
                userDto = user;
                break;
            }
        }


        return user;
    }


    /**
     * 删除用户
     * */
    @ApiOperation("删除用户")
    @DeleteMapping("/users/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public Object deleteUser(@PathVariable("id") Long id){
        List<UserDto> list = getData();
        UserDto userDto = getUserDto(id, list);
        return  userDto;
    }


    /**
     * 模拟数据
     * */
    private List<UserDto> getData(){
        List<UserDto> list=new ArrayList<>();


        UserDto userDto = new UserDto();
        userDto.setId(1L);
        userDto.setName("admin");
        userDto.setPwd("admin");
        list.add(userDto);


        userDto = new UserDto();
        userDto.setId(2L);
        userDto.setName("HogwartsTest1");
        userDto.setPwd("HogwartsTest1");
        list.add(userDto);


        userDto = new UserDto();
        userDto.setId(3L);
        userDto.setName("HogwartsTest2");
        userDto.setPwd("HogwartsTest2");
        list.add(userDto);


        userDto = new UserDto();
        userDto.setId(4L);
        userDto.setName("HogwartsTest3");
        userDto.setPwd("HogwartsTest3");
        list.add(userDto);


        return  list;
    }


    /**
     *  模拟根据id查询列表中的数据
     * @param id
     * @param list
     * @return
     */
    private UserDto getUserDto( Long id, List<UserDto> list) {
        UserDto UserDto = null;
        for (UserDto user : list) {
            if (id.equals(user.getId())) {
                UserDto = user;
                break;
            }
        }
        return UserDto;
    }
}

UserDto.java

 @ApiModel(value = "用户登录类", description = "请求类")
 public class UserDto {


     @ApiModelProperty(value="用户id", example="1",required=true)
     private Long id;


     @ApiModelProperty(value="用户名称", example="hogwarts1",required=true)
     private String name;


     @ApiModelProperty(value="用户密码", example="hogwarts2",required=true)
     private String pwd;


     public Long getId() {
         return id;
     }


     public void setId(Long id) {
         this.id = id;
     }


     public String getName() {
         return name;
     }


     public void setName(String name) {
         this.name = name;
     }


     public String getPwd() {
         return pwd;
     }


     public void setPwd(String pwd) {
         this.pwd = pwd;
     }
 }

Spring Boot 集成 Swagger就先讲到这里，大家可以照着代码，多练习一下哦~
获取更多相关资料：
https://qrcode.ceba.ceshiren.com/link?name=article&project_id=qrcode&from=hwyun&timestamp=1653815818&author=MM