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-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 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 文档。

相关文章