运用 Swagger 自动生成 RESTful API 文档-JavaScript中文网-JavaScript教程资源分享门户

在前端开发中，我们经常需要与后端进行交互，而 RESTful API 是目前最常用的一种方式之一。在与后端进行开发过程中，一个我们必须要面对的问题就是 API 文档的编写和更新，这对于我们来说是一件繁琐且易出错的事情。而 Swagger 就提供了一种方便快捷的方式来自动生成 RESTful API 文档，极大地减少了我们的开发成本。

什么是 Swagger？

Swagger 是一个开源的 API 文档生成工具，它支持 RESTful API 规范，可以自动生成高质量的 API 文档。Swagger 主要支持 YAML 或 JSON 格式的 API 文档描述文件，通过各种工具可以把这些描述文件转成丰富的 API 文档，可以包括 API 的参数、请求方式、响应信息、错误码等内容。

Swagger 的优点

自动生成文档：通过 Swagger，能够自动生成 API 文档，减少了手写文档的步骤，减少出错的可能性；
规范接口：通过定义接口规范和文档，使得接口规范和文档能够进行统一管理，方便日后维护；
调试接口：Swagger 提供了测试接口的功能，可以使接口在调试时更容易理解；
接口可视化：Swagger 提供了友好的界面，使得接口信息可以通过可视化界面进行查看。

如何使用 Swagger 自动生成 RESTful API 文档？

下面让我们来一步步探讨如何使用 Swagger 自动生成 RESTful API 文档。

安装 Swagger

在使用 Swagger 之前，我们需要先安装它。Swagger 的安装非常简单，只需要运行以下指令即可：

npm install -g swagger

编写 Swagger 描述文件

接下来，需要编写一个描述文件，该文件是 Swagger 自动生成 RESTful API 文档的依据。在描述文件中，我们需要指定 API 的基本信息、请求参数和响应等信息。

例如，我们有一个简单的 API，用于获取用户信息。我们可以使用以下描述文件来描述它：

// javascriptcn.com 代码示例
swagger: '2.0'
info:
  title: User API
  version: 1.0.0
  description: API for user management
basePath: /api/v1
paths:
  /user/{id}:
    get:
      summary: Get user by ID
      description: Retrieve the user object based on user ID
      operationId: getUserById
      produces:
        - application/json
      parameters:
        - name: id
          in: path
          description: ID of the user to fetch
          required: true
          type: integer
      responses:
        200:
          description: User object
          schema:
            $ref: "#/definitions/User"
        404:
          description: User not found
definitions:
  User:
    type: object
    properties:
      id:
        type: string
      name:
        type: string
      age:
        type: integer
      gender:
        type: string

在上面的描述文件中，我们定义了一个 GET 请求，路径是 /user/{id}，返回的结果是一个 User 对象。具体的解释可以参考注释。

生成 API 文档

我们已经编写好了描述文件，接下来就可以生成 API 文档了。使用 Swagger，我们可以使用命令行或 Web 界面两种方式。

命令行生成 API 文档

使用 Swagger 生成 API 文档非常简单，只需要执行以下命令即可：

swagger generate spec -i <input-file> -o <output-file>

其中，<input-file> 是我们编写的 Swagger 描述文件，可以是 json 或 yaml 格式；<output-file> 是生成的 API 文档的存储路径和文件名。

例如，我们可以使用以下命令来生成 API 文档：

swagger generate spec -i user-api.yaml -o user-api.json

这将把 user-api.yaml 描述文件转换成 user-api.json API 文档。

Web 界面生成 API 文档

Swagger 还提供了一个 Web 界面，可以让我们更方便地生成 API 文档。只需要访问以下网址即可：

http://localhost:8080/swagger/

在 Web 界面中，我们需要输入 API 的基本信息，然后通过可视化的方式来输入请求参数、响应等信息，最终生成的 API 文档可以直接在文档中进行查看。

查看 API 文档

生成 API 文档之后，我们就可以来查看它，确认生成的文档是否符合我们的预期。除了使用 Swagger 提供的 Web 界面进行查看之外，我们还可以使用 Swagger UI 工具来展示 API 文档。

在使用 Swagger UI 展示 API 文档之前，我们需要先安装它。只需要执行以下命令即可：

npm install swagger-ui

安装完成后，我们需要在 HTML 文件中添加以下代码：

// javascriptcn.com 代码示例
<!DOCTYPE html>
<html>
  <head>
    <title>Swagger UI</title>
    <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" >
  </head>
  <body>
    <div id="swagger-ui"></div>
    <script src="dist/swagger-ui-bundle.js"></script>
    <script src="dist/swagger-ui-standalone-preset.js"></script>
    <script>
      window.onload = function() {
        var ui = SwaggerUIBundle({
          url: "user-api.json",
          dom_id: '#swagger-ui',
          deepLinking: true,
          presets: [
            SwaggerUIBundle.presets.apis,
            SwaggerUIStandalonePreset
          ],
          plugins: [
            SwaggerUIBundle.plugins.DownloadUrl
          ],
          layout: "StandaloneLayout"
        })
      }
    </script>  
  </body>
</html>

其中，url 属性是我们已经生成的 API 文档路径，需要注意路径的正确性。

当我们在浏览器中打开这个 HTML 文件时，就可以看到一个完整的 API 文档，包括接口信息、请求参数和响应等内容。

总结

在本文中，我们学习了 Swagger 描述文件的编写方法、Swagger 工具的使用方法以及如何使用 Swagger UI 展示 API 文档。通过使用 Swagger，我们可以方便快捷地生成高质量的 RESTful API 文档，减少了手动编写文档的步骤，提高了我们的开发效率。同时，Swagger 还可以规范我们的接口规范和文档，易于管理和后期维护。

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