swagger讲解

时间:2024-10-15 14:17:06

超详细 Swagger 使用指南(附带注解总结和源码)_swagger使用-****博客 

实践

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

Swagger 的核心组件

使用 Swagger 的优势

如何在项目中集成 Swagger

1. 在 Spring Boot 中集成 Swagger

Spring Boot 项目中集成 Swagger 是一个常见的做法,可以使用 springdoc-openapiswagger-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 API
        version: 1.0.0
      paths:
        /users:
          get:
            summary: Get all users
            responses:
              '200':
                description: A list of users
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        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 文档。