发布于 由admin

SSM 集成 Swagger/OpenAPI：自动化 API 文档生成

SSM 集成 Swagger/OpenAPI：告别手写 API 文档，拥抱自动化！

各位看官，大家好！今天咱们聊点轻松又实用的话题：SSM（Spring + SpringMVC + MyBatis）框架集成 Swagger/OpenAPI，打造自动化 API 文档生成利器。

想象一下，你辛辛苦苦写了一堆 API 接口，功能强大，性能卓越，结果呢？前端小哥苦苦哀求：“大哥，你的接口咋用啊？参数是啥？返回值是啥？Demo 有木有？” 你只好放下手头的工作，一遍又一遍地解释，一遍又一遍地写 Demo，时间就这么悄悄溜走了，头发也越来越少了…

别慌！Swagger/OpenAPI 来了！它就像一位贴心的 API 文档管家，能自动帮你生成美观、易懂、可交互的 API 文档，解放你的双手，拯救你的发际线。

一、 Swagger/OpenAPI 是什么？

简单来说，Swagger/OpenAPI 是一套用于设计、构建、记录和使用 RESTful API 的完整工具集。它包括：

  • OpenAPI Specification (OAS)： 一种标准的 API 描述格式，用 JSON 或 YAML 编写，定义了 API 的结构、参数、返回值等信息。
  • Swagger UI： 一个美观、可交互的 Web 界面，用于展示 OpenAPI 描述的 API 文档。你可以像浏览网页一样，查看 API 的详细信息，甚至直接在 UI 上发送请求进行测试。
  • Swagger Editor： 一个在线编辑器，用于编写和编辑 OpenAPI 描述文件。
  • Swagger Codegen： 一个代码生成器，可以根据 OpenAPI 描述文件生成各种语言的客户端代码和服务端代码。

二、 为什么要集成 Swagger/OpenAPI？

  • 自动化文档生成： 告别手写 API 文档的时代，Swagger 可以根据代码自动生成 API 文档，大大提高了开发效率。
  • 实时更新： 只要代码更新，API 文档也会自动更新，保证文档的准确性。
  • 可交互性： Swagger UI 提供了一个可交互的界面，你可以直接在 UI 上发送请求，查看响应结果，方便 API 的测试和调试。
  • 前后端分离协作： 前端开发人员可以通过 Swagger 文档了解 API 的详细信息，无需依赖后端开发人员的口头描述，提高协作效率。
  • 提高代码质量： 为了让 Swagger 能够正确生成 API 文档，你需要编写规范的代码，这在一定程度上提高了代码质量。

三、 如何在 SSM 项目中集成 Swagger/OpenAPI？

这里我们以 Swagger 3 (OpenAPI 3) 为例，介绍如何在 SSM 项目中集成 Swagger。

1. 添加 Maven 依赖

首先，在 pom.xml 文件中添加 Swagger 3 的相关依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.15</version>
</dependency>

<!-- 解决一些兼容性问题，可选 -->
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>4.15.5</version>
</dependency>

解释：

  • springdoc-openapi-ui：这是 SpringDoc 提供的 Swagger UI 集成，它可以自动扫描 Spring MVC 控制器，生成 OpenAPI 描述文件，并提供 Swagger UI 界面。
  • org.webjars:swagger-ui：这个依赖有时候可以解决一些兼容性问题，确保 Swagger UI 能够正常显示。

2. 配置 SwaggerConfig

创建一个配置类 SwaggerConfig，用于配置 Swagger 的相关信息：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.info.License;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("我的 API 文档")
                        .version("1.0")
                        .description("这是我的 API 文档，欢迎使用！")
                        .termsOfService("http://example.com/terms/")
                        .license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

解释：

  • @Configuration：表示这是一个配置类。
  • @Bean：表示这是一个 Spring Bean，会被 Spring 容器管理。
  • OpenAPI：OpenAPI 的根对象，用于配置 API 的全局信息。
  • Info：用于配置 API 的基本信息，例如标题、版本、描述、服务条款、许可证等。
  • License：用于配置 API 的许可证信息。

3. 在 Controller 中添加 Swagger 注解

在你的 Spring MVC 控制器中，添加 Swagger 注解，用于描述 API 的相关信息：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/users")
@Tag(name = "用户管理", description = "用户管理相关的 API 接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户信息", description = "根据用户 ID 获取用户信息")
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(schema = @Schema(implementation = User.class)))
    @ApiResponse(responseCode = "404", description = "用户不存在")
    public User getUser(@Parameter(description = "用户 ID") @PathVariable Long id) {
        // 模拟从数据库中获取用户
        if (id == 1) {
            return new User(1L, "张三", "[email protected]");
        } else {
            return null;
        }
    }

    @PostMapping
    @Operation(summary = "创建用户", description = "创建一个新的用户")
    @ApiResponse(responseCode = "201", description = "创建成功", content = @Content(schema = @Schema(implementation = User.class)))
    @ApiResponse(responseCode = "400", description = "请求参数错误")
    public User createUser(@RequestBody @Parameter(description = "用户信息") User user) {
        // 模拟保存用户到数据库
        user.setId(2L);
        return user;
    }
}

// 简单的 User 类
class User {
    private Long id;
    private String name;
    private String email;

    public User() {}

    public User(Long id, String name, String email) {
        this.id = id;
        this.name = name;
        this.email = email;
    }

    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 getEmail() {
        return email;
    }

    public void setEmail(String email) {
        this.email = email;
    }
}

解释：

  • @Tag：用于对 Controller 进行分组，方便管理 API。
  • @Operation：用于描述 API 的基本信息，例如摘要、描述等。
  • @Parameter：用于描述 API 的参数，例如参数名称、描述等。
  • @ApiResponse：用于描述 API 的响应，例如状态码、描述、响应内容等。
  • @Schema：用于描述 API 的数据模型，例如类的属性、类型等。
  • @RequestBody：表示请求体中的参数。
  • @PathVariable：表示 URL 路径中的参数。

4. 启动项目，访问 Swagger UI

启动你的 SSM 项目，然后在浏览器中访问 http://localhost:8080/swagger-ui/index.html（端口号根据你的项目配置而定）。你就可以看到 Swagger UI 界面了，里面展示了你的 API 文档。

四、 常用 Swagger 注解详解

  • @Tag： 用于对 Controller 或 API 进行分组。

    • name：分组名称。
    • description：分组描述。
    @Tag(name = "用户管理", description = "用户管理相关的 API 接口")
public class UserController {
    // ...
}

  • @Operation： 用于描述 API 的基本信息。

    • summary：API 摘要，简要描述 API 的功能。
    • description：API 详细描述，可以包含更详细的信息。
    • tags：API 所属的标签，可以用于对 API 进行分类。
    • operationId：API 的唯一标识符。
    • deprecated：表示 API 是否已弃用。
    @Operation(summary = "获取用户信息", description = "根据用户 ID 获取用户信息")
public User getUser(@PathVariable Long id) {
    // ...
}

  • @Parameter： 用于描述 API 的参数。

    • name：参数名称。
    • description：参数描述。
    • required：表示参数是否必填。
    • in：参数的位置，例如 path (URL 路径), query (URL 查询参数), header (请求头), cookie (Cookie), body (请求体)。
    • schema：参数的类型和格式。
    public User getUser(@Parameter(description = "用户 ID", required = true) @PathVariable Long id) {
    // ...
}

  • @ApiResponse： 用于描述 API 的响应。

    • responseCode：HTTP 状态码。
    • description：响应描述。
    • content：响应内容，例如 JSON 数据。
      • @Content：用于描述响应内容的类型和格式。
        • schema：响应内容的类型，例如 String, Integer, Object 等。
          • @Schema：用于描述数据模型的属性和类型。
    @ApiResponse(responseCode = "200", description = "成功", content = @Content(schema = @Schema(implementation = User.class)))
@ApiResponse(responseCode = "404", description = "用户不存在")
public User getUser(@PathVariable Long id) {
    // ...
}

  • @Schema： 用于描述数据模型的属性和类型。

    • name：属性名称。
    • description：属性描述。
    • type：属性类型，例如 string, integer, number, boolean, array, object 等。
    • format：属性格式，例如 date, date-time, email, password 等。
    • required：表示属性是否必填。
    • example：属性示例值。
    class User {
    @Schema(description = "用户ID", example = "123")
    private Long id;
    @Schema(description = "用户名", example = "张三")
    private String name;
    @Schema(description = "用户邮箱", example = "[email protected]")
    private String email;

    // ...
}

五、 进阶技巧

  • 配置分组： 如果你的项目中有多个模块，可以将 API 分成不同的组，方便管理。可以通过配置多个 OpenAPI Bean 来实现。

    @Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI userOpenAPI() {
        return new OpenAPI()
                .groupName("用户管理") // 设置分组名称
                .info(new Info()
                        .title("用户管理 API 文档")
                        .version("1.0")
                        .description("用户管理相关的 API 接口"));
    }

    @Bean
    public OpenAPI productOpenAPI() {
        return new OpenAPI()
                .groupName("商品管理") // 设置分组名称
                .info(new Info()
                        .title("商品管理 API 文档")
                        .version("1.0")
                        .description("商品管理相关的 API 接口"));
    }
}

    然后在 Swagger UI 界面上，就可以看到不同的分组了。

  • 自定义 UI： 你可以自定义 Swagger UI 的样式和行为，例如修改标题、logo、主题等。可以通过配置文件或 Java 代码来实现。

    在 application.properties 或 application.yml 中添加配置：

    springdoc.swagger-ui.config-url=/v3/api-docs/swagger-config
springdoc.swagger-ui.layout=StandaloneLayout
springdoc.swagger-ui.disable-try-it=true

  • 集成 Spring Security： 如果你的 API 使用了 Spring Security 进行权限控制，你需要配置 Swagger，使其能够正确处理认证和授权。这通常涉及到配置 SecurityScheme 和 SecurityRequirement。

    @Bean
public OpenAPI customizeOpenAPI() {
    final String securitySchemeName = "bearerAuth";
    return new OpenAPI()
            .addSecurityItem(new SecurityRequirement().addList(securitySchemeName))
            .components(
                    new Components()
                            .addSecuritySchemes(securitySchemeName,
                                    new SecurityScheme()
                                            .name(securitySchemeName)
                                            .type(SecurityScheme.Type.HTTP)
                                            .scheme("bearer")
                                            .bearerFormat("JWT")
                            )
            )
            .info(new Info()
                    .title("我的 API 文档")
                    .version("1.0")
                    .description("这是我的 API 文档，欢迎使用！")
            );
}

  • 使用 Swagger Codegen： 可以根据 OpenAPI 描述文件生成客户端代码和服务端代码，方便 API 的使用和开发。

    例如，可以使用以下命令生成 Java 客户端代码：

    java -jar swagger-codegen-cli.jar generate -i swagger.json -l java -o output

六、 注意事项

  • 保持 API 文档与代码同步： Swagger 只能根据代码生成 API 文档，如果代码更新了，务必及时更新 Swagger 注解，保证文档的准确性。
  • 编写清晰的描述： 尽量编写清晰、易懂的 API 描述，方便其他开发人员理解 API 的功能和使用方法。
  • 合理使用 Swagger 注解： 不要滥用 Swagger 注解，只添加必要的注解，避免代码过于冗余。
  • 安全性： 在生产环境中，需要对 Swagger UI 进行安全保护，避免泄露敏感信息。可以配置 Spring Security，限制 Swagger UI 的访问权限。

七、 总结

通过集成 Swagger/OpenAPI，我们可以轻松实现 API 文档的自动化生成，提高开发效率，方便 API 的测试和调试，促进前后端分离协作。虽然配置和使用需要一些学习成本，但收益是巨大的。

所以，还在手动编写 API 文档的你，赶紧行动起来，拥抱 Swagger/OpenAPI 吧！让它成为你开发过程中的得力助手，解放你的双手，拯救你的发际线！

希望这篇文章对你有所帮助。如果你有任何问题，欢迎留言交流！

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注