README

swagger-php

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

有关支持的所有注释的完整列表，请参阅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 doanphu/swagger-php-trigger-error

从任何位置使用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();

从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 Issues 或 pull requests。

文档网站是由 docs 文件夹和 vitepress 构建的。

确保 pull requests 通过 PHPUnit 和 PHP-CS-Fixer (PSR-2) 测试。

要运行单元测试和代码风格检查，执行

composer test

要运行静态分析，执行

composer analyse

仅运行单元测试

./bin/phpunit

重新生成注解/属性参考文档

composer docs:refgen

仅运行代码风格检查

composer lint

要使用 php-cs-fixer 修复代码风格错误

composer cs