SpringBoot3.x玩转Swagger神器，让接口文档不再捉襟见肘

2024-01-07 05:19:53

SpringBoot 3.x 中使用 Swagger 的终极指南：暂用 OpenApi Generator

前言

在当今的软件开发世界中，前后端分离已成为主流。API 文档对于团队协作、项目管理、敏捷开发甚至是 DevOps 都至关重要。作为 SpringBoot 开发者，我们自然要紧跟时代，了解 Spring 生态系统中使用 Swagger 的最新动态。

什么是 Swagger？

Swagger 是一套强大的工具，用于生成、维护和使用 RESTful API 文档。它提供了一系列功能，包括：

代码生成： 基于 OpenAPI 规范生成客户端代码（支持多种语言）。
文档生成： 基于 OpenAPI 规范生成 API 文档（支持 HTML、JSON、Markdown 等格式）。
测试： 提供测试框架，帮助开发人员测试 API。
模拟服务器： 模拟 API 服务器，方便开发人员进行测试和调试。

SpringBoot 中的 Swagger 之选：Springfox

在 SpringBoot 中，Springfox 是使用 Swagger 的最佳选择。它是一个 Spring Boot starter，提供了一组现成的注解和配置，使开发人员能够轻松地为其 RESTful API 添加 Swagger 支持。

Springfox 的遗憾：暂不支持 SpringBoot 3.x

然而，遗憾的是，Springfox 目前暂不支持 SpringBoot 3.x。这给许多开发者带来了困扰。不过，我们不必过于担心，因为 Springfox 社区正在积极努力，争取尽快发布对 SpringBoot 3.x 的支持。

应急之策：OpenApi Generator

在等待 Springfox 支持 SpringBoot 3.x 的这段时间里，我们可以使用 OpenApi Generator 来生成 API 文档。OpenApi Generator 是一款代码生成工具，可以基于 OpenAPI 规范生成客户端代码、服务器代码和文档。

OpenApi Generator 操作指南

安装 OpenApi Generator。
创建一个新的 OpenAPI 规范文件。
使用 OpenApi Generator 生成代码和文档。

具体操作步骤

1. **安装 OpenApi Generator** 

使用以下命令安装 OpenApi Generator：

pip install openapi-generator


2. **创建 OpenAPI 规范文件** 

创建 OpenAPI 规范文件，例如 `api.yaml`：

```yaml
openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: Get all users
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string

使用 OpenApi Generator 生成代码和文档

使用以下命令生成代码和文档：

openapi-generator generate -i api.yaml -g python -o client

这将生成客户端代码、服务器代码和文档到 client 目录。

结语

Swagger 是生成、维护和使用 RESTful API 文档的利器。Springfox 是 SpringBoot 中使用 Swagger 的最佳选择，但目前暂不支持 SpringBoot 3.x。我们可以使用 OpenApi Generator 作为应急之策。相信不久的将来，Springfox 也会支持 SpringBoot 3.x，届时我们将可以更加轻松地使用 Swagger 来生成 API 文档。

常见问题解答