README

swagger-php

使用 doctrine 注释生成 RESTful API 的交互式 OpenAPI 文档。

关于这个分支

此分支添加了通过指定 enumCallback 属性来确定枚举值的功能。

/**
 * @OA\Property(type="string", enumCallback="\My\Class::myMethod")
 */

将自动将 enum 属性设置为 array_values() 的返回值，该返回值由 \MyClass\::myMethod() 方法提供。

功能

• 兼容 OpenAPI 3.0 规范。
• 从代码和现有的 phpdoc 注释中提取信息。
• 提供命令行界面。
• 文档网站，包含入门指南。
• 出色的错误报告（带有提示和上下文）

安装（使用 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\scan('/path/to/project');
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

从命令行界面使用

将文档生成到静态 json 文件中。

./vendor/bin/openapi --help

从反序列化器使用

从 json 字符串生成 OpenApi 注释对象，这使得以编程方式操作对象变得更加容易。

<?php

use OpenApi\Serializer;

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

从 docker 使用

将 Swagger 文档生成到静态 json 文件中。

docker run -v "$PWD":/app -it tico/swagger-php --help

关于 OpenApi 和 Swagger 的更多信息

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

贡献

请随意提交 Github 问题 或拉取请求。

文档网站由 docs 文件夹和 vuepress 构建。

确保拉取请求通过 PHPUnit 和 PHP_CodeSniffer（PSR-2）测试。

要运行 unittests 和 linting，请执行

composer test

仅运行 unittests

./bin/phpunit

仅运行 linting

./bin/phpcs -p --extensions=php --standard=PSR2 --error-severity=1 --warning-severity=0 ./src ./tests