配置自动生成 Swagger 文档

Swagger

Swagger 是一个开源工具，它围绕 OpenAPI 规范构建，帮助开发人员设计、构建、文档化和消费 RESTful API。它是用于 RESTful Web 服务的最流行的 API 文档格式。它提供了 JSON 和用户界面（UI）支持。JSON 可以用作机器可读的格式，Swagger-UI 则用于可视化展示，使人们只需浏览 API 文档就能理解。主要的 Swagger 工具包括：

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

OpenAPI 规范（以前称为 Swagger 规范）是用于 REST API 的 API 文档格式。OpenAPI 文件允许我们描述整个 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 cn.javatiku.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 http://localhost:8080/v2/api-docs

它会显示完整的文档，以 JSON 格式呈现，如下图所示。这不太容易阅读和理解。Swagger 已经提供了该格式，可用于其他系统，如提供 API 网关、API 缓存、API 文档等功能的 API 管理工具。

如果我们想与客户分享 Web 服务的文档，我们可以共享此 JSON 文件。

现在在浏览器中键入 URI http://localhost:8080/swagger-ui.html。它会显示我们创建的服务的文档。

我们还可以展开服务，查看其中包含哪些操作。在下图中，我们展开了用户资源服务。 以上翻译为中文。