Swagger2：API 开发与文档生成的得力助手

原创已于 2025-04-26 17:52:41 修改 · 1k 阅读

18 ·

CC 4.0 BY-SA版权

文章标签：

#swagger2 #java #eclipse #tomcat

于 2025-04-26 17:48:58 首次发布

Swagger2：API 开发与文档生成的得力助手

一、引言

在现代软件开发中，API（应用程序接口）扮演着至关重要的角色。无论是前后端分离的架构，还是微服务架构，API 都是不同组件之间进行交互的桥梁。随着项目规模的扩大和团队协作的增多，如何高效地设计、开发、测试和维护 API 成为了一个关键问题。Swagger2 应运而生，它为 API 的全生命周期管理提供了一套完整的解决方案，从设计阶段的可视化展示，到开发过程中的代码集成，再到测试和文档生成，都有着出色的表现。

二、Swagger2 简介

2.1 什么是 Swagger2

Swagger2 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web API。它提供了一系列的工具和标准，使得开发人员可以轻松地定义 API 的结构、参数、响应等信息，并自动生成详细的 API 文档。同时，Swagger2 还支持在线测试 API，方便开发人员和测试人员进行接口调试。

2.2 Swagger2 的核心组件

Swagger 规范（OpenAPI 规范）：它是 Swagger 的基础，定义了一种语言无关的 API 描述格式，用于描述 RESTful API 的各个方面，包括路径、操作、参数、响应等。目前 Swagger 规范已经演进为 OpenAPI 规范，两者在很大程度上是兼容的。
Swagger Editor：这是一个基于浏览器的可视化工具，允许开发人员使用 YAML 或 JSON 格式编写 API 定义。通过 Swagger Editor，开发人员可以直观地定义 API 的结构和细节，并且实时预览 API 文档的效果。
Swagger UI：它是一个基于 Web 的界面，用于展示 Swagger 定义的 API 文档。Swagger UI 可以将 API 定义以美观、易读的方式呈现出来，并且提供了在线测试 API 的功能，方便开发人员和其他相关人员快速了解 API 的功能和使用方法。
Swagger Codegen：这是一个代码生成工具，它可以根据 Swagger 定义自动生成多种编程语言的 API 客户端代码和服务端代码骨架。这大大提高了开发效率，减少了手动编写代码的工作量，并且保证了代码与 API 定义的一致性。

2.3 Swagger2 的优势

提高 API 文档质量：传统的 API 文档可能存在更新不及时、描述不清晰等问题。而 Swagger2 生成的文档是根据 API 的实际定义自动生成的，保证了文档与代码的一致性，并且文档内容详细、规范，易于理解。
增强团队协作：在团队开发中，不同的成员可能负责不同的模块，Swagger2 提供的统一的 API 描述方式和可视化界面，使得团队成员可以方便地了解彼此开发的 API 接口，减少沟通成本，提高协作效率。
方便 API 测试：Swagger UI 提供的在线测试功能，使得开发人员和测试人员可以直接在浏览器中对 API 进行测试，无需使用额外的测试工具，方便快捷。
支持多语言开发：Swagger Codegen 支持生成多种编程语言的代码，无论是 Java、Python、JavaScript 还是其他语言，都可以根据 Swagger 定义快速生成相应的代码，适应不同的开发需求。

三、Swagger2 快速入门

3.1 环境准备

在开始使用 Swagger2 之前，需要确保已经安装了相关的开发环境。以下是一些常见的环境要求：

Java 环境：如果是在 Java 项目中使用 Swagger2，需要安装 JDK（建议使用 8 及以上版本）。
构建工具：常用的构建工具如 Maven 或 Gradle，用于管理项目的依赖和构建过程。
Web 框架：例如 Spring Boot、Spring MVC 等，Swagger2 可以与这些 Web 框架很好地集成。

3.2 在 Java Spring Boot 项目中集成 Swagger2

以 Java Spring Boot 项目为例，以下是集成 Swagger2 的具体步骤：

3.2.1 添加依赖

如果使用 Maven 管理项目依赖，在 pom.xml 文件中添加以下依赖：

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

如果使用 Gradle，在 build.gradle 文件中添加：

compile group: 'io.springfox', name:'springfox-swagger2', version: '2.9.2'
compile group: 'io.springfox', name:'springfox-swagger-ui', version: '2.9.2'

3.2.2 配置 Swagger2

在 Spring Boot 项目中创建一个配置类，例如 SwaggerConfig.java，用于配置 Swagger2：

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

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
               .apiInfo(apiInfo())
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
               .paths(PathSelectors.any())
               .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
               .title("Spring Boot Swagger2 API 文档")
               .description("这是一个使用 Swagger2 生成的 API 文档示例")
               .version("1.0")
               .build();
    }
}

在上述代码中：

@EnableSwagger2 注解用于启用 Swagger2 功能。
Docket 类是 Swagger2 的核心配置类，通过它可以定义 API 的基本信息，如 API 标题、描述、版本等，还可以指定扫描的控制器包路径（这里是 com.example.demo.controller）以及要包含的路径。
apiInfo 方法用于构建 API 的详细信息。

3.2.3 编写 API 接口

在 com.example.demo.controller 包下创建一个控制器类，例如 UserController.java，编写一些简单的 API 接口：

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
public class UserController {

    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "User with id " + id;
    }

    @PostMapping
    public String createUser(@RequestBody String user) {
        return "Created user: " + user;
    }
}

这里定义了两个简单的 RESTful API 接口，一个用于根据用户 ID 获取用户信息，另一个用于创建用户。

3.2.4 启动项目并访问 Swagger UI

启动 Spring Boot 项目后，在浏览器中访问 http://localhost:8080/swagger-ui.html（假设项目运行在 8080 端口），就可以看到生成的 Swagger UI 界面，在该界面中可以查看 API 的详细信息并进行在线测试。

四、Swagger2 详细配置与使用

4.1 定义 API 信息

在 SwaggerConfig 类中，通过 ApiInfo 来定义 API 的详细信息，除了前面提到的标题、描述和版本外，还可以添加更多信息：

private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
           .title("Spring Boot Swagger2 API 文档")
           .description("这是一个使用 Swagger2 生成的 API 文档示例")
           .version("1.0")
           .termsOfServiceUrl("https://www.example.com/terms")
           .contact(new Contact("Your Name", "https://www.example.com", "your.email@example.com"))
           .license("Apache 2.0")
           .licenseUrl("https://www.apache.org/licenses/LICENSE-2.0.html")
           .build();
}

上述代码中：

termsOfServiceUrl 设置 API 的服务条款地址。
Contact 用于指定 API 维护者的联系信息，包括姓名、个人网站和邮箱。
license 和 licenseUrl 分别设置 API 的许可证名称和许可证地址。

4.2 扫描 API 接口

在 Docket 的配置中，通过 apis 和 paths 方法来指定要扫描的 API 接口：

apis 方法：常用的选择器有 RequestHandlerSelectors.basePackage，用于指定扫描的基础包路径，只有在该包及其子包下的控制器类中的 API 接口才会被 Swagger2 识别。还可以使用 RequestHandlerSelectors.withClassAnnotation 方法，通过指定类上的注解来筛选控制器类，例如 RequestHandlerSelectors.withClassAnnotation(RestController.class) 表示只扫描带有 @RestController 注解的类。
paths 方法：PathSelectors.any() 表示包含所有路径的 API 接口，也可以使用 PathSelectors.regex 方法通过正则表达式来匹配特定的路径，例如 PathSelectors.regex("/users/.*") 表示只包含以 /users/ 开头的路径的 API 接口。

4.3 定义 API 参数

4.3.1 路径参数

在 API 接口方法中，使用 @PathVariable 注解定义的参数就是路径参数。例如：

@GetMapping("/{id}")
public String getUserById(@PathVariable Long id) {
    return "User with id " + id;
}

在 Swagger UI 中，会自动识别并展示该路径参数的名称和类型。

4.3.2 查询参数

对于使用 @RequestParam 注解的查询参数，例如：

@GetMapping("/search")
public String searchUsers(@RequestParam String keyword) {
    return "Search results for keyword: " + keyword;
}

Swagger2 会将其展示为可输入的查询参数，并且可以设置参数的默认值、是否必填等属性。可以通过 @ApiParam 注解来进一步丰富参数描述：

@GetMapping("/search")
public String searchUsers(@ApiParam(value = "搜索关键词", required = true) @RequestParam String keyword) {
    return "Search results for keyword: " + keyword;
}

4.3.3 请求体参数

当 API 接口接收 JSON 格式的请求体时，使用 @RequestBody 注解。例如：

import com.example.demo.model.User;

@PostMapping
public String createUser(@RequestBody User user) {
    return "Created user: " + user.toString();
}

这里的 User 类可以是一个自定义的实体类，Swagger2 会根据类的属性自动生成请求体的结构描述。可以在 User 类的属性上使用 @ApiModelProperty 注解来描述属性的含义：

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

@ApiModel("用户实体类")
public class User {

    @ApiModelProperty("用户 ID")
    private Long id;

    @ApiModelProperty("用户姓名")
    private String name;

    // 省略 getters 和 setters
}

4.4 定义 API 响应

可以使用 @ApiResponse 注解来定义 API 接口的响应信息。例如：

@GetMapping("/{id}")
@ApiResponse(code = 200, message = "成功获取用户信息")
public String getUserById(@PathVariable Long id) {
    return "User with id " + id;
}

还可以使用 @ApiResponses 注解来定义多个不同的响应情况：

@GetMapping("/{id}")
@ApiResponses({
        @ApiResponse(code = 200, message = "成功获取用户信息"),
        @ApiResponse(code = 404, message = "用户未找到")
})
public String getUserById(@PathVariable Long id) {
    return "User with id " + id;
}

对于复杂的响应对象，同样可以在响应类的属性上使用 @ApiModelProperty 注解来详细描述响应内容。

4.5 分组管理 API

有时候一个项目中会有多个不同类型的 API 接口，为了更好地管理和展示，可以对 API 进行分组。在 Docket 配置中，可以通过 groupName 方法来指定分组名称：

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
           .groupName("用户相关 API")
           .apiInfo(apiInfo())
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.user"))
           .paths(PathSelectors.any())
           .build();
}

@Bean
public Docket orderApi() {
    return new Docket(DocumentationType.SWAGGER_2)
           .groupName("订单相关 API")
           .apiInfo(apiInfo())
           .select()
           .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller.order"))
           .paths(PathSelectors.any())
           .build();
}

这样在 Swagger UI 中就会分别展示不同分组的 API 接口。

五、Swagger Editor 使用

5.1 安装与启动 Swagger Editor

Swagger Editor 可以在线使用，访问 Swagger Editor 官网即可直接在浏览器中使用。也可以将其部署到本地服务器上，具体步骤如下：

下载 Swagger Editor 的代码仓库，可以从 GitHub 仓库克隆代码。
进入项目目录，安装依赖：
- 如果使用 npm，执行 npm install。
启动服务：
- 使用 npm 执行 npm start，然后在浏览器中访问 http://localhost:3000（默认端口为 3000），即可看到 Swagger Editor 界面。

5.2 使用 Swagger Editor 编写 API 定义

Swagger Editor 使用 YAML 或 JSON 格式来编写 API 定义。以下是一个简单的 YAML 格式的 API 定义示例：

swagger: "2.0"
info:
  title: My API
  description: This is a sample API description
  version: "1.0"
host: localhost:8080
basePath: /api
schemes:
  - http
paths:
  /users:
    get:
      summary: Get all users
      responses:
        200:
          description: A list of users
          schema:
            type: array
            items:
              $ref: '#/definitions/User'
    post:
      summary: Create a new user
      parameters:
        - name: user
          in: body
          required: true
          schema:
            $ref: '#/definitions/User'
      responses:
        201:
          description: User created successfully
definitions:
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string

在上述代码中：

swagger 字段指定 Swagger 规范的版本。
info 部分定义 API 的基本信息，如标题、描述和版本。
host 和 basePath 用于指定 API 的主机地址和基础路径。
schemes 定义 API 使用的协议（这里是 http）。
paths 部分定义 API 的路径和对应的操作（如 get 和 post），每个操作包含摘要、参数和响应等信息。
definitions 用于定义可复用的数据模型（这里是 User 模型）。

通过 Swagger Editor 的可视化界面，可以方便地编写和编辑这些内容，并且可以实时预览生成的 API 文档效果。同时，Swagger Editor 还提供了语法检查和自动补全等功能，提高了编写效率和准确性。

5.3 导出与分享 API 定义

在 Swagger Editor 中编写好 API 定义后，可以将其导出为 YAML 或 JSON 文件，方便在项目中使用或与其他团队成员分享。点击界面右上角的“下载”按钮，选择相应的文件格式即可进行导出。此外，还可以通过在线分享功能，生成一个分享链接，其他人员通过该链接可以直接查看和编辑 API 定义（如果设置了可编辑权限）。

六、Swagger UI 定制

6.1 自定义 Swagger UI 界面样式

可以通过覆盖 Swagger UI 的默认 CSS 样式来定制界面外观。首先，将 Swagger UI 的 CSS 文件下载到项目中，然后在 HTML 页面中引入该 CSS 文件，并添加自定义的样式。例如，在 index.html 文件中：

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">