配置 Swagger 文档的自动生成

2025年1月20日 | 阅读时长 2 分钟

Swagger

Swagger 是一种开源工具。它围绕 OpenAPI 规范构建，可帮助开发人员设计、构建、记录和使用 RESTful API。它是 RESTful Web Services 最流行的 API 文档格式。它同时提供 JSON 和 UI 支持。JSON 可以用作机器可读的格式，而 Swagger-UI 用于可视化显示，只需浏览 API 文档即可轻松理解。主要的 Swagger 工具包括：

Swagger UI: 它创建交互式 API 文档。
Swagger Editor: 这是一个基于浏览器的编辑器，我们可以在其中编写 OpenAPI 规范。
Swagger Codegen: 它生成服务器存根（API 实现存根）和客户端库，从而形成 OpenAPI 规范。

OpenAPI 规范（以前称为 Swagger 规范）是 REST API 的 API 文档格式。Open API 文件允许我们描述整个 API，包括：

可用的端点 (/users) 和每个端点上的操作 (GET /users, POST /users)。
每个操作的操作参数。
身份验证方法。
联系信息、许可证、使用条款和其他信息。

让我们为 RESTful 服务生成 Swagger 文档。

步骤 1: 打开 pom.xml 并添加 springfox-swagger2 依赖项。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

添加另一个依赖项 springfox-swagger-ui

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

现在我们需要配置 Swagger。

步骤 2: 创建一个名为 SwaggerConfig.java 的类，并编写以下代码。

Docket: 一个构建器，旨在成为 swagger-Spring MVC 框架的主要接口。 Docket 为配置提供了合理的默认值和便捷的方法。

package com.javatpoint.server.main;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//creating bean
@Bean
public Docket api()
{
//creating constructor of Docket class that accepts parameter DocumentationType
return new Docket(DocumentationType.SWAGGER_2);
}
}

步骤 3: 运行应用程序。

步骤 4: 打开浏览器并输入 URI https://:8080/v2/api-docs

它以 JSON 格式显示完整的文档，如下图所示。它不容易阅读和理解。 Swagger 提供了它，以便在其他系统中（如 API 管理工具）使用，这些工具提供 API 网关、API 缓存、API 文档等功能。