PHP开发：如何利用 Swagger 维护 API 文档-php教程-PHP中文网

PHP开发：如何利用 Swagger 维护 API 文档

WBOY

发布： 2023-06-15 09:38:01

原创

1014 人浏览过

随着互联网的快速发展，Web API 成为了支撑开放式应用的核心所在。API 的可扩展性和可重用性使得它们成为了不同系统之间数据交换和协同的重要工具。然而，开发人员往往会遇到一个常见的问题：如何维护 API 文档并确保 API 的可靠性？

Swagger 是一个开源的框架，它提供了 API 设计、文档编制、测试和部署的全套解决方案。本文将探讨如何使用 Swagger 维护 API 文档，以便更好地管理和维护现有的 API。

一、Swagger 的基础概念

Swagger 通过描述 API 的 JSON 或 YAML 规范文件来创建和文档化 API。这个文件称为 Swagger 规范。

Swagger 规范文件包含以下概念：

路径：API 路径是资源的标识符。例如，/users 表示所有用户，/users/{id} 表示一个用户。
方法：一种 HTTP 方法，例如 GET、PUT、POST、DELETE 和 HEAD。
参数：请求参数（HTTP 请求正文、URL 路径和/或查询字符串参数）。
响应：HTTP 响应结构、状态码和响应体（HTTP 响应正文）类型。
模型：数据传输对象（DTO）和响应对象的结构。
标签：对 API 资源进行逻辑分组，方便阅读。

二、Swagger 的使用

安装 Swagger UI

Swagger UI 是一个开源的工具，允许我们在一个交互式的界面中显示 Swagger 规范文件。它的主要作用是提供一个清晰而可交互的文档，并允许我们测试和调试 API。

使用以下命令安装 Swagger UI：

npm install swagger-ui-dist

登录后复制

编写 Swagger 规范文件

编写 Swagger 规范文件，以说明我们的 API 的路径、方法、参数、响应等信息。

下面是一个示例：

swagger: '2.0'
info:
  title: User API Root
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      description: Returns all users
      produces:
        - application/json
      responses:
        200:
          description: A list of user names
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 123
              name:
                type: string
                example: John Doe

登录后复制

在这个例子中，我们定义了一个 API 路径“/users”和一个 GET 方法，返回一个包含“id”和“name”的 JSON 对象数组作为响应。

集成 Swagger UI

在你的 Web 应用程序中集成 Swagger UI，以便显示你的 Swagger 规范文件。添加以下 HTML 代码到你的 Web 页面中：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Swagger UI</title>
  <link rel="stylesheet" type="text/css" href="./node_modules/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="./node_modules/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    window.onload = function() {
      SwaggerUIBundle({
        url: "https://api.example.com/swagger",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
    }
  </script>
</body>
</html>

登录后复制

在这个例子中，我们在 HTML 文件中加载 Swagger UI，并将 Swagger 规范文件的 URL 地址传递给 SwaggerUIBundle，以呈现 API 文档。