当前位置：首页 > 文章列表 > 文章 > php教程 > 手把手教你用OpenAPI快速生成PHP项目API文档（超简单）

手把手教你用OpenAPI快速生成PHP项目API文档（超简单）

2025-06-22 18:49:30 0浏览收藏

还在为PHP项目的API文档编写效率低下而烦恼吗？本文将手把手教你如何利用OpenAPI规范快速生成标准化、交互式的PHP API文档，告别手动编写的繁琐。文章详细介绍了使用Swagger UI、Swagger Editor以及zircote/swagger-php等工具，从编写OpenAPI规范文件，到代码注释生成规范，再到配置Swagger UI展示文档，最后将文档集成到构建流程并部署到生产环境的全过程。通过学习本文，你将掌握API文档自动生成的核心技巧，确保文档与代码同步更新，提升开发效率，并为你的API提供清晰、易用的文档支持。

使用OpenAPI规范生成PHP API文档的核心方法包括：1.选择合适工具，如Swagger UI、Swagger Editor及zircote/swagger-php等；2.编写OpenAPI规范文件，定义API基本信息、端点、参数、响应和数据模型；3.可选地通过代码注释生成规范文件，利用工具扫描代码自动创建文档；4.配置Swagger UI展示文档，创建HTML页面并正确指向OpenAPI规范文件；5.将文档集成到构建流程中实现自动化生成；6.部署文档至生产环境时托管静态文件、配置服务器、处理CORS、身份验证及版本控制。整个过程确保文档与代码同步更新，并提供标准化、交互式的API文档展示。

PHP中的API文档：如何使用OpenAPI规范生成文档

直接使用OpenAPI规范（以前称为Swagger规范）可以让你从代码注释或其他源文件生成PHP API文档。这不仅能保持文档的最新状态，还能提供一个标准化的方式来描述你的API。

使用OpenAPI规范生成PHP API文档的核心在于定义API的结构和行为，然后利用工具将这些定义转换成可读的文档。

解决方案

选择合适的工具：
- Swagger UI： 一个流行的工具，可以根据OpenAPI规范动态地生成漂亮的、交互式的API文档。
- Swagger Editor： 一个用于编辑OpenAPI规范的在线编辑器，可以实时预览文档。
- 其他代码生成工具： 例如zircote/swagger-php，可以从PHP代码注释生成OpenAPI规范。
编写OpenAPI规范：
- 可以使用YAML或JSON格式编写OpenAPI规范文件（例如openapi.yaml或openapi.json）。
- 定义API的基本信息，例如标题、版本、描述等。
- 详细描述每个API端点（paths），包括请求方法（GET、POST等）、参数、请求体、响应状态码和响应体。
- 定义数据模型（components/schemas），描述API中使用的数据结构。
使用代码注释生成OpenAPI规范（可选）：
- 使用zircote/swagger-php或其他类似的库，可以在PHP代码中使用注释来描述API。
- 运行工具扫描代码，生成OpenAPI规范文件。
使用Swagger UI展示文档：
- 将OpenAPI规范文件配置到Swagger UI中。
- 通过浏览器访问Swagger UI，即可查看生成的API文档。
自动化文档生成：
- 将文档生成过程集成到你的构建流程中，例如使用Makefile或CI/CD工具。
- 每次代码更新后，自动生成最新的API文档。

如何在PHP项目中安装和配置Swagger UI？

Swagger UI 需要一些配置才能在你的 PHP 项目中正确运行。首先，你需要下载 Swagger UI 的发行包，或者使用 CDN。然后，你需要创建一个 HTML 页面来加载 Swagger UI，并配置它指向你的 OpenAPI 规范文件。

以下是一个简单的示例：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" type="text/css" href="swagger-ui.css" >
  <title>Swagger UI</title>
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="swagger-ui-bundle.js"> </script>
  <script>
    window.onload = function() {
      const ui = SwaggerUIBundle({
        url: "openapi.yaml", // 你的 OpenAPI 规范文件路径
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIBundle.presets.default
        ],
        plugins: [
          SwaggerUIBundle.plugins.Unstable.Oas3Convert
        ],
        layout: "StandaloneLayout"
      })
      window.ui = ui
    }
  </script>
</body>
</html>

将 openapi.yaml 替换为你实际的 OpenAPI 规范文件路径。确保 swagger-ui.css 和 swagger-ui-bundle.js 的路径正确。

使用zircote/swagger-php从PHP代码注释生成OpenAPI规范的示例

zircote/swagger-php 是一个很棒的工具，可以让你直接在 PHP 代码中编写 OpenAPI 注释。

首先，你需要安装它：

composer require zircote/swagger-php

然后，在你的 PHP 代码中添加注释：

<?php
/**
 * @OA\Info(
 *   title="My API",
 *   version="1.0.0"
 * )
 */

/**
 * @OA\Get(
 *   path="/users/{id}",
 *   summary="Get user by ID",
 *   @OA\Parameter(
 *     name="id",
 *     in="path",
 *     description="User ID",
 *     required=true,
 *     @OA\Schema(
 *       type="integer"
 *     )
 *   ),
 *   @OA\Response(
 *     response=200,
 *     description="Successful operation",
 *     @OA\JsonContent(
 *       type="object",
 *       @OA\Property(property="id", type="integer"),
 *       @OA\Property(property="name", type="string")
 *     )
 *   )
 * )
 */
function getUser($id) {
  // ...
}

最后，运行 swagger-php 命令来生成 OpenAPI 规范文件：

./vendor/bin/swagger -o openapi.yaml ./path/to/your/php/files

将 ./path/to/your/php/files 替换为包含你的 PHP 文件的目录。

如何将生成的API文档部署到生产环境？

部署 API 文档到生产环境通常涉及以下步骤：

静态文件托管： 将 Swagger UI 的静态文件（CSS、JavaScript、HTML）上传到你的 Web 服务器或 CDN。
配置 Web 服务器： 配置你的 Web 服务器（例如 Apache、Nginx）来提供 Swagger UI 的静态文件。
CORS 配置： 如果你的 API 和 Swagger UI 部署在不同的域名下，你需要配置 CORS (跨域资源共享) 策略，允许 Swagger UI 访问你的 API。
安全考虑： 如果你的 API 需要身份验证，你需要配置 Swagger UI 来传递身份验证信息（例如 API 密钥、JWT）。
版本控制： 确保你的 API 文档与你的 API 版本同步。可以使用版本控制系统 (例如 Git) 来管理你的 OpenAPI 规范文件。

今天带大家了解了的相关知识，希望对你有所帮助；关于文章的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~

swaggerui OpenAPI规范 PHPAPI文档 zircote/swagger-php 自动化生成