PHP 项目怎么输出 Swagger 文档？swagger-php 是一个常用的选项，接下来介绍下 swagger-php 的使用。
swagger-php 介绍
swagger-php 可以生成版本为 3.0 或 3.1 的 OpenAPI 文档。
swagger-php 允许你在 PHP 源代码中记录你的 API。 swagger-php 注释可以是 docblocks 或 PHP 8.1 属性。
swagger-php 快速上手
安装 swagger-php
composer require zircote/swagger-php
工具入口
<?phprequire("vendor/autoload.php");
$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();
Controller 使用示例
<?phpuse OpenApi\Annotations as OA;/**
* @OA\Info(
* title="My First API",
* version="0.1"
* )
*/class OpenApi {}class MyController {/**
* @OA\Get(
* path="/api/data.json",
* @OA\Response(
* response="200",
* description="The data"
* )
* )
*/public function getResource() {// ...}}
输出文档
./bin/openapi src -o openapi.yaml
使用 PHP attributes
PHP8 引入了属性（attributes）的概念，它是一种新的语言特性，用于向类、方法、函数、参数等结构添加元数据（metadata）。属性可以通过一组语法糖（syntax sugar）来声明和使用，这些语法糖可以放在类、方法、函数、参数等结构的声明前面，也可以放在这些结构的注释中。
属性可以用于各种用途，例如：
- 注解（annotation）：通过属性可以为类、方法、函数、参数等结构添加注解信息，例如@Route、@Inject等。
- 类型约束（type hinting）：通过属性可以为参数、返回值等添加类型约束，例如#[ParamType]、#[ReturnType]等。
- 代码生成（code generation）：通过属性可以为类、方法、函数、参数等结构添加代码生成信息，例如#[Getter]、#[Setter]等。
在 PHP 8中，属性可以通过反射机制访问和操作，这使得开发者可以在运行时检查和修改属性。同时，PHP 8 还提供了一些内置的属性，例如 #[Deprecated]、#[Final]、#[Internal] 等，用于标记过时、不可继承、内部使用等情况。
<?php
namespace OpenApi\Examples\UsingLinksPhp81;
use OpenApi\Attributes as OAT;
#[OAT\Schema(schema: 'repository')]
class Repository
{
/**
* @var string
*/
#[OAT\Property(type: 'string')]
public $slug;
#[OAT\Property()]
public User $owner;
}
小结
在生成 swagger 文件后，会有小伙伴直接分享 Swagger JSON 或者 OpenAPI yaml 给其他协作者， 我一般都会吐槽下，不得不说，这都 2023 了，这种方式太 Outdate 了， 建议直接使用 Apifox 的 API 分享功能，简单安全。API 一体化工具，可以帮助开发人员在一个平台上完成 API 相关的多项任务。
- API 设计和文档生成：Apifox 提供了易于使用的接口设计工具，可以帮助你设计和生成 OpenAPI 和 Swagger 文档。
- API 管理和测试：你可以使用 Apifox 管理 API，并使用内置的测试工具测试 API 的功能和性能。
- API 自动化：Apifox 提供了自动化工具和功能，例如将 API 集成到你的 CI/CD 流程中，以便自动构建和部署 API。
