README

swagger-php

使用 doctrine annotations 为您的 RESTful API 生成交互式 OpenAPI 文档。

有关支持的完整注释列表，请参阅 OpenApi\Annotations 命名空间 或 文档网站。

功能

• 兼容 OpenAPI 3.0 和 3.1 规范。
• 从代码和现有的 phpdoc 注释中提取信息。
• 提供命令行界面。
• 具有入门指南的 文档网站。
• 出色的错误报告（带有提示和上下文）
• 从 PHP 8.1 开始，所有注释也可以作为 PHP 属性使用

OpenAPI 版本支持

swagger-php 允许生成 OpenAPI 3.0.0 或 OpenAPI 3.1.0 规格的规范。默认情况下，规范将使用版本 3.0.0。可以使用命令行选项 --version 将此更改为 3.1.0。

程序上，可以使用 Generator::setVersion() 方法来更改版本。

要求

swagger-php 至少需要 PHP 7.2 来使用注释，PHP 8.1 来使用属性。

安装（使用 Composer）

composer require zircote/swagger-php

要从任何地方使用 cli，请全局安装 swagger-php 并确保将 ~/.composer/vendor/bin 目录添加到您的 PATH，以便系统可以找到 openapi 可执行文件。

composer global require zircote/swagger-php

使用

将注释添加到您的 php 文件中。

/**
 * @OA\Info(title="My First API", version="0.1")
 */

/**
 * @OA\Get(
 *     path="/api/resource.json",
 *     @OA\Response(response="200", description="An example resource")
 * )
 */

访问 文档网站 以获取 入门指南 或查看 示例目录 以获取更多示例。

从 php 使用

生成始终是最新的文档。

<?php
require("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

有关 Generator 类的文档，请参阅 Generator 参考。

从命令行界面使用

可以使用 openapi 命令行界面将文档生成到静态 yaml/json 文件。

./vendor/bin/openapi --help

从版本 4 开始，命令行上使用的默认分析器是新的 ReflectionAnalyser。

使用 --legacy 标志（-l）仍可以使用旧的 TokenAnalyser。

从反序列化器使用

从 json 字符串生成 OpenApi 注释对象，这使得程序上操作对象更容易。

<?php

use OpenApi\Serializer;

$serializer = new Serializer();
$openapi = $serializer->deserialize($jsonString, 'OpenApi\Annotations\OpenApi');
echo $openapi->toJson();

贡献

更多关于 OpenApi 和 Swagger 的信息

• https://swagger.org.cn
• https://openapis.org.cn
• OpenApi 文档
• OpenApi 规范
• 相关项目