README

注意

从https://github.com/sintbert/swagger-php复制并修改

swagger-php

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

特性

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

安装（使用Composer）

composer require avency/swagger-php

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

composer global require avency/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 Issues或拉取请求。

文档网站是从docs文件夹使用vuepress构建的。

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

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

composer test

仅运行单元测试

./bin/phpunit

仅运行代码检查

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