「实践经验」如何使用 Swagger 构建 RESTful API 文档

在现代的应用中，API（Application Programming Interface）已经成为不可或缺的一部分。关于如何正确地设计和文档化 API，是每个开发者必须掌握的技能。

Swagger 是一种流行的 API 设计和文档化工具，它提供了一套标准化的方式来描述 RESTful APIs。在本文中，我们将介绍如何使用 Swagger 构建 RESTful API 文档。

什么是 Swagger？

Swagger 是一种开源的 API 规范，允许开发者用简单的 JSON 或 YAML 格式描述他们的 RESTful API。在规范定义的基础上，Swagger 提供了一组工具来自动生成文档、生成客户端代码和执行测试。

Swagger 可以帮助开发者：

• 描述 API 的请求、响应和认证方式。
• 自动生成符合规范的 API 文档。
• 生成客户端 SDK。
• 提供交互式 API 测试界面。

如何使用 Swagger？

以下是使用 Swagger 构建 RESTful API 文档的步骤：

1. 安装 Swagger

npm install swagger-ui-express swagger-jsdoc

2. 创建 Swagger 规范文件

用 YAML 或 JSON 方式创建 Swagger 规范文件。下面是一个示例：

// javascriptcn.com 代码示例
swagger: "2.0"
info:
  version: "1.0.0"
  title: "My API"
  description: "This is a simple API"
host: "localhost:3000"
basePath: "/api"
schemes:
  - "http"
  - "https"
paths:
  /users:
    get:
      summary: "Get all users"
      description: "Return a list of all users"
      produces:
        - "application/json"
      responses:
        200:
          description: "successful operation"
          schema:
            type: "array"
            items:
              $ref: "#/definitions/User"
    post:
      summary: "Create a new user"
      description: "Create a new user with the given information"
      parameters:
        - name: "user"
          in: "body"
          required: true
          schema:
            $ref: "#/definitions/User"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/User"
definitions:
  User:
    type: "object"
    properties:
      id:
        type: "integer"
      name:
        type: "string"
      email:
        type: "string"
      password:
        type: "string"

以上是一个简单的例子，它定义了一个 /users 路径，包含一个 GET 请求方法和一个 POST 方法。每个请求都包括描述、参数、响应状态码等信息。

3. 将 Swagger 集成到应用中

在你的 Express 应用中添加以下代码：

// javascriptcn.com 代码示例
const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');

const options = {
    definition: {
        openapi: '3.0.0',
        info: {
            title: 'My API',
            version: '1.0.0',
        },
    },
    // 路径可以自己根据项目情况设置，文件名也需要与之前创建的 Swagger 规范文件相同
    apis: ['./routes/*.js', './swagger.yaml'],
};

const specs = swaggerJsdoc(options);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));

// 其他路由定义

app.listen(3000, () => {
    console.log('Server started on port 3000');
});

4. 访问 Swagger UI

在浏览器中输入 http://localhost:3000/api-docs，你将看到 Swagger UI 页面。您可以使用该页面测试 API、查看规范文件和生成客户端 SDK。

总结

Swagger 是一种流行的 API 设计和文档化工具，它可以根据描述 RESTful API

来源：JavaScript中文网 ，转载请注明来源 本文地址：https://www.javascriptcn.com/post/651afe6295b1f8cacd2c1b2e