JAVA：Spring Boot 整合 Swagger 的技术指南

请关注微信公众号：拾荒的小海螺
博客地址：http://lsk-ww.cn/

1、简述

在现代Web开发中，API文档的生成和维护是非常重要的。Swagger是一款流行的API文档生成工具，它可以帮助开发者自动生成API文档，并提供可视化的接口测试功能。本文将介绍如何在Spring Boot项目中集成Swagger，快速生成API文档。

官网地址：https://swagger.io/

2、 准备工作

在开始集成Swagger之前，确保你的开发环境已经安装并配置好了以下工具：

• Java JDK：建议使用JDK 8或以上版本。
• Maven：用于依赖管理和构建项目。
• Spring Boot：确保已有一个Spring Boot项目。

3、集成Swagger

Swagger是一套开源工具，用于设计、构建、文档化和使用RESTful Web服务。通过注解，Swagger可以自动生成功能全面的API文档，提供直观的接口信息和在线测试功能。

3.1 添加Swagger依赖

首先，在你的Spring Boot项目的pom.xml文件中添加Swagger相关的依赖：

<dependencies>
    <!-- Swagger依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
    <!-- 其他依赖 -->
</dependencies>

3.2 创建Swagger配置类

在项目中创建一个Swagger配置类，用于配置Swagger的基本信息和扫描路径。新建一个类SwaggerConfig：

package com.xhl.shiro.config;

import io.swagger.annotations.ApiOperation;
import io.swagger.models.Contact;
import com.google.common.base.Function;
import com.google.common.base.Optional;
import com.google.common.base.Predicate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import springfox.documentation.RequestHandler;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig implements WebMvcConfigurer {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //包下的类，才生成接口文档
                //.apis(RequestHandlerSelectors.basePackage("com.xhl.shiro.controller"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(security());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("Spring Boot 集成 Swagger 示例")
                .version("1.0.0")
                .build();
    }

    private List<SecurityScheme> security() {
        return newArrayList(
                new ApiKey("token", "token", "header")
        );
    }

}

在上述配置中，RequestHandlerSelectors.basePackage方法指定了Swagger要扫描的包路径，你可以根据项目结构进行调整。

3.3 集成Swagger UI

在Swagger官网下载最新的UI(https://swagger.io/tools/swagger-ui/download/)：

git clone https://github.com/swagger-api/swagger-ui.git
cd swagger-ui

然后通过npm指令安装和编译：

npm install
npm run build

然后把编译完成在dist目录下的所有文件拷贝到项目/resources/static/swagger：

3.4 注解控制器类和方法

Swagger通过注解来生成API文档。在控制器类和方法上使用Swagger注解，描述API接口信息。例如：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/users")
public class UserController {

    @Autowired
    private UserService userService;

    @ApiOperation("获取所有用户")
    @GetMapping
    public List<UserEntity> list() {
        return userService.list();
    }

    @ApiOperation("添加新用户")
    @PostMapping
    public void save(@RequestBody UserEntity user) {
        userService.save(user);
    }

    @ApiOperation("更新用户信息")
    @PutMapping
    public void update(@RequestBody UserEntity user) {
        userService.updateById(user);
    }

    @ApiOperation("删除用户")
    @DeleteMapping("/{id}")
    public void delete(@PathVariable Long id) {
        userService.removeById(id);
    }
}

Swagger常用注解说明：

• @Api：用在类上，说明该类的作用。

• @ApiOperation：注解来给API增加方法说明。

• @ApiParam：定义在参数上

• @ApiResponses：用于表示一组响应

• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  code：数字，例如400
  message：信息，例如"请求参数没填好"
  response：抛出异常的类

• @ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

• @ApiModelProperty：描述一个model的属性

• @ApiImplicitParams: 用在方法上包含一组参数说明。

• @ApiImplicitParam：用来注解来给方法入参增加说明。

• @ApiImplicitParam的参数说明：
  paramType：指定参数放在哪个地方
  header：请求参数放置于Request Header，使用@RequestHeader获取
  query：请求参数放置于请求地址，使用@RequestParam获取
  path：（用于restful接口）–>请求参数的获取：@PathVariable body：（不常用） form（不常用）
  name：参数名
  dataType：参数类型
  required：参数是否必须传 true | false
  value：说明参数的意思
  defaultValue：参数的默认值

3.5 访问Swagger UI

启动Spring Boot项目后，打开浏览器访问http://localhost:8080/swagger/，你将看到Swagger自动生成的API文档界面。在这个界面中，你可以查看所有API的详细信息，并进行在线测试。

服务端接口文档路径：http://localhost:8080/v2/api-docs，通过Explore导入：

4、配置Swagger的更多选项

Swagger提供了丰富的配置选项，你可以根据项目需求进行定制。例如：

• 设置全局参数：可以在Swagger配置类中设置全局的请求头、响应头等。
• 分组API：通过设置不同的Docket实例，可以将API分组展示。
• 安全配置：可以集成OAuth2、JWT等认证方式，保护API接口。

@Bean
public Docket customDocket() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.xhl.shiro"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(securitySchemes())
            .securityContexts(securityContexts());
}

5、总结

通过集成Swagger，开发者可以轻松地生成和维护API文档，提高开发效率和API的可用性。在Spring Boot项目中，Swagger的集成过程相对简单，只需添加依赖、配置类和注解即可完成。希望通过本文的介绍，你能够在自己的项目中顺利集成Swagger，为API文档的生成和维护提供便利。