超详细 Swagger 使用指南（附带注解总结和源码）_swagger使用-CSDN博客 

实践

Swagger 是一套用于生成、描述、文档化和消费 RESTful Web 服务的开源工具。它帮助开发者以一种标准化的方式定义 API，从而更方便地进行 API 开发、测试和集成。Swagger 通过标准化 RESTful API 的文档，使得客户端和服务端的开发者可以轻松理解和使用 API，而无需依赖额外的说明文档。

Swagger 的核心组件

使用 Swagger 的优势

如何在项目中集成 Swagger

1. 在 Spring Boot 中集成 Swagger

Spring Boot 项目中集成 Swagger 是一个常见的做法，可以使用 springdoc-openapi 或 swagger-springfox 库。以下是使用 springdoc-openapi 集成的示例：

步骤：

2. 在 Node.js 中集成 Swagger

在 Node.js 项目中，你可以使用 swagger-jsdoc 来生成 API 文档，结合 swagger-ui-express 来展示这些文档。

步骤：

1. Swagger UI：

   • 一个基于 HTML/JavaScript 的用户界面，用于在线展示 API 文档，并允许用户通过浏览器直接测试 API。
   • Swagger UI 可以从 OpenAPI 规范中读取 API 文档并展示出来，提供可视化的接口展示。

2. Swagger Editor：

   • 一个在线编辑器，开发者可以在其中编写 OpenAPI 规范文档。它提供了即时的可视化和验证支持，帮助开发者更方便地定义 API 文档。

3. Swagger Codegen：

   • 这个工具可以基于 API 的定义自动生成客户端 SDK、服务器端代码以及 API 文档等多种格式，支持多种编程语言。

4. OpenAPI Specification (OAS)：

   • Swagger 使用 OpenAPI 规范（之前称为 Swagger 规范）来定义和描述 RESTful API。这是一种基于 JSON 或 YAML 的标准格式，用于描述 API 的端点、请求/响应结构、参数、错误等信息。
   • 目前 OpenAPI 规范已成为行业标准，被广泛应用于 API 文档化。

5. Swagger 的工作原理

6. 定义 API：

   • 开发者使用 YAML 或 JSON 格式的 OpenAPI 规范定义 API，包括路径（endpoints）、请求参数、响应格式、安全机制等。
   • 示例 API 定义（YAML）：

     openapi: 3.0.0
     info:title: Sample APIversion: 1.0.0
     paths:/users:get:summary: Get all usersresponses:'200':description: A list of userscontent:application/json:schema:type: arrayitems:type: string
     

7. 展示和测试 API：

   • 通过 Swagger UI，用户可以直观地看到 API 的结构和文档。Swagger UI 提供了一种交互式的方式来查看 API 的路径、参数、请求类型和响应等信息。
   • Swagger UI 允许用户直接测试 API，比如在页面中填入参数并发送请求，查看返回结果。

8. 生成代码：

   • 使用 Swagger Codegen，开发者可以从 API 文档中自动生成服务器端代码、客户端 SDK 以及 API 的静态文档。例如，可以通过 Codegen 生成 Java、Python、Go 等语言的客户端库，方便 API 的快速集成。

9. 集成到项目中：

   • 在许多现代框架中，Swagger 已经与服务器端代码生成或自动化文档生成集成。例如在 Java 的 Spring Boot 项目中，可以通过注解生成 Swagger 文档，而在 Node.js 或 Python 中也有类似的工具集成。

10. 标准化文档：通过使用 OpenAPI 规范，API 文档格式统一，使得开发、测试和使用 API 的团队可以在一个平台上方便地理解 API。

11. 自动生成代码和文档：Swagger 提供了自动生成服务器端代码、客户端 SDK 和静态文档的功能，减少了手动编写代码和文档的工作量，并且保证文档与代码的一致性。

12. 方便的接口测试：通过 Swagger UI，开发者和测试人员可以直接在浏览器中测试 API 的功能，而无需额外的测试工具（如 Postman）。

13. 快速集成：Swagger Codegen 支持多种语言和框架，可以自动生成客户端代码，从而快速集成 API。

14. 添加依赖：

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

15. 启动后，访问 http://localhost:8080/swagger-ui.html 即可查看生成的 API 文档。

16. 用注解定义 API：

    @RestController
    @RequestMapping("/api")
    public class UserController {@Operation(summary = "Get all users")@GetMapping("/users")public List<String> getAllUsers() {return Arrays.asList("John", "Jane", "Doe");}
    }
    

17. 启动 Spring Boot 应用，Swagger UI 会自动根据注解生成 API 文档。

18. 安装依赖：

    npm install swagger-jsdoc swagger-ui-express

19. 配置 Swagger：

    const swaggerJsDoc = require('swagger-jsdoc');
    const swaggerUi = require('swagger-ui-express');
    const express = require('express');
    const app = express();const swaggerOptions = {swaggerDefinition: {openapi: "3.0.0",info: {title: "Sample API",version: "1.0.0",description: "A sample API documentation"},servers: [{url: "http://localhost:5000"}]},apis: ["app.js"] // 定义 API 的路径
    };const swaggerDocs = swaggerJsDoc(swaggerOptions);
    app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocs));app.listen(5000, () => {console.log("Server running on port 5000");
    });
    

20. 定义 API 路由，并添加注释来生成文档：

    /*** @swagger* /users:*   get:*     summary: Returns a list of users*     responses:*       200:*         description: A JSON array of user names*/
    app.get('/users', (req, res) => {res.json(["John", "Jane", "Doe"]);
    });
    

21. 启动服务器后，访问 http://localhost:5000/api-docs 即可查看生成的 API 文档。