后端API设计文档代码生成【免费下载链接】swagger-phpA php swagger annotation and parsing library项目地址https://gitcode.com/gh_mirrors/sw/swagger-php点击查看免费下载swagger-php是一个用 PHP 编写的 OpenAPI 文档生成库让你通过 PHP 属性Attributes首选方式或 doctrine 注解需额外安装doctrine/annotations为 RESTful API 添加元数据然后自动产出可交互的 OpenAPI 规范文档YAML/JSON。本文以仓库根目录的 README.md 为主线结合 Builder、GenerateCommand、TypeInfoTypeResolver 等源码实现讲解安装、命令行与编程式生成、三种处理模式classic/hybrid/spec以及 v6 自动类型解析等核心能力读完即可在项目中直接落地生成 API 文档。项目定位与核心特性swagger-php定位是面向 PHP 代码的 OpenAPI 生成器扫描代码中的结构元素类、方法、属性、常量等把上面的属性/注解翻译成符合 OpenAPI 规范的文档结构。官方 README 列出如下核心特性兼容 OpenAPI 3.0、3.1、3.2 三种规范版本可针对同一份代码产出不同版本的规格文档从代码与既有 phpdoc 注释中提取信息降低手写文档的重复劳动既支持编程式调用也支持命令行工具bin/openapi完善的错误报告附带提示信息hints与上下文contextSpec 属性Beta一套可以用手直接构建、无需扫描即可编译的属性体系配套的管道能在属性写错时直接报告错误详见 Why spec attributes?。OpenAPI 版本支持README 明确说明swagger-php可以生成OpenAPI 3.0.0、3.1.0、3.2.0三种版本的规格文档且版本选择与处理模式相关classic 模式默认输出3.0.0spec 与 hybrid 模式默认输出3.1.0命令行通过--version选项切换目标版本编程式调用通过Builder::setVersion()切换。从源码看版本的分发机制位于 src/Builder.php构建时会先解析版本优先级为setVersion()显式指定 源码中#[OpenApi(version: ...)] 默认3.1.0再通过resolveCompiler()从 OpenApi30Compiler、OpenApi31Compiler、OpenApi32Compiler 三个编译器中选择支持该版本的实现若找不到匹配的编译器会抛出OpenApiExceptionNo compiler available for version ...。这正是版本是编译器而不是分支的设计目标版本不具备的关键字由编译器统一丢弃或告警。环境要求README 明确swagger-php要求PHP 8.2 及以上。这一要求在 composer.json 的require.php字段8.2中也有体现同时它依赖nikic/php-parser、phpstan/phpdoc-parser、symfony/console、symfony/yaml等库。安装项目级与全局级项目内安装推荐composer require zircote/swagger-php全局安装命令行使用如果想在任何目录下使用openapi命令可全局安装并把 Composer 的全局 bin 目录加入系统 PATH可通过composer global config bin-dir --absolute查询该目录composer global require zircote/swagger-php全局安装后系统即可定位到openapi可执行文件bin/openapi。doctrine/annotations 说明自4.8 版本起doctrine/annotations库变为可选依赖不再默认安装。如果你的代码仍使用 doctrine 注解/** OA\... */风格需要手动安装composer require doctrine/annotations注意文档中已声明注解方式已被弃用**Annotations are deprecated and may be removed in a future release of swagger-php.**未来版本可能移除新代码应优先使用 PHP 属性。基本用法用属性标注你的 API在类、方法等结构元素上使用OpenApi\Attributes命名空间下的属性来添加元数据。README 给出了最小示例use OpenApi\Attributes as OAT; #[OAT\Info(title: My First API, version: 0.1)] class MyApi { #[OAT\Get(path: /api/resource.json)] #[OAT\Response(response: 200, description: An example resource)] public function getResource() { // ... } }关于属性的写法官方文档 using-attributes 还补充了两点实用技巧命名空间别名所有属性都在OpenApi\Attributes命名空间建议用use OpenApi\Attributes as OA;别名简化书写嵌套与平铺两种写法等价子元素既可以嵌套在父属性内也可以平铺在同一个目标上swagger-php会按父子关系规则自动合并。例如下面两种写法等价// 嵌套写法 #[OA\Get( path: /api/users, responses: [ new OA\Response(response: 200, description: OK), new OA\Response(response: 401, description: Not allowed), ] )] public function users() { /* ... */ } // 平铺写法自动合并 #[OA\Get(path: /api/users)] #[OA\Response(response: 200, description: OK)] #[OA\Response(response: 401, description: Not allowed)] public function users() { /* ... */ }需要留意属性的自动合并只发生在顶层例如方法users()上更深层的嵌套仍需显式书写。仓库提供了完整的可运行示例例如 docs/examples/specs/api/attributes/OpenApiSpec.php 展示了#[OAT\OpenApi]、#[OAT\Info]、#[OAT\License]、#[OAT\Server]、#[OAT\SecurityScheme]、#[OAT\Tag]的组合用法Product.php 则展示了在类常量、属性、构造器参数上使用#[OAT\Property]的写法均可作为上手参考对应生成结果在docs/examples/specs各子目录下的 YAML 文件中例如 petstore 示例 petstore-3.0.0.yaml。 Spec AttributesBeta新的处理模式自 6.5.0 起可用这是 README 重点介绍的实验性能力一套使用OpenApi\Spec命名空间、带类型约束的属性。它的核心差异是属性本身就是普通的数据容器Typed DTO构造器提升属性直接带类型声明因此可以脱离扫描、手工构建并直接编译。编写示例use OpenApi\Spec as OA; #[OA\OpenApi(version: 3.1.0)] #[OA\Info(title: My API, version: 1.0)] class MyApi { #[OA\Operation\Get(path: /api/resource)] #[OA\Response(response: 200, description: An example resource)] public function getResource() {} }注意命名空间从OpenApi\Attributes变为OpenApi\SpecHTTP 方法从#[OA\Get]变为#[OA\Operation\Get]。关于 Spec 属性 API 的完整细节Schema、Operations、PathItem、Components、Security、与 classic 属性的差异等参见 Using Spec Attributes。编程式使用 Spec 模式$result (new \OpenApi\Builder()) -setMode(\OpenApi\Builder\Mode::SPEC) -addSource(src/) -build();Hybrid 模式零改动的过渡路径Hybrid 模式对已有的OpenApi\Attributes代码完全兼容、无需任何改动它仍运行经典扫描器但复用新的 augmenter 管道与版本感知编译器后者更易于扩展。切换 Hybrid 也是帮助测试新管道最简单的方式$result (new \OpenApi\Builder()) -setMode(\OpenApi\Builder\Mode::HYBRID) -addSource(src/) -build();命令行等价写法./vendor/bin/openapi src/ --mode hybrid。三种模式的底层差异从源码看三种模式的管道实现如下对应 Builder.php 的build()分发逻辑与官方 Processing Modes 文档维度Classic默认HybridBetaSpecBeta状态稳定BetaBeta属性命名空间OpenApi\AttributesOpenApi\AttributesOpenApi\Spec注解支持是是否管道Generator → ProcessorsAssembler → Resolver → HybridBridge → Augmenters → CompilerAssembler → Resolver → Augmenters → Compiler版本感知编译否单一序列化器是是未引用组件默认保留默认移除并记录 notice默认移除并记录 noticeClassic经Generator及其处理器链构建文档可通过withGenerator()使用完整的GeneratorAPI自定义处理器、分析器、配置等Spec从零重写管道引入分组 augmenterresolve → reduce → augment 三阶段与按版本拆分的编译器Hybrid先用经典Generator扫描再由 HybridBridge 把Analysis中的经典注解逐个转换成SpecificationfromAnalysis()中通过match分发转换OpenApi、Info、Server、Tag、SecurityScheme、Operation、Schema等各类注解随后交给 spec 管道的 augmenters 与编译器见 Builder.php。模式切换方式CLI 用./vendor/bin/openapi src/ --mode spec -o openapi.yaml或--mode hybridPHP 用$builder-setMode(Mode::SPEC)或$builder-setMode(spec)。模式枚举定义在 src/Builder/Mode.phpclassic/hybrid/spec。⚠️ Beta 提示Spec 模式功能已基本完整但仍属 Beta属性 API 可能在未来的大版本中演进。官方规划见 modes.md 的版本时间线v6 以 opt-in Beta 形式提供 spec/hybridclassic 仍为默认v7 hybrid 成为默认模式v8 classic 被移除、Spec 成为默认并迁移到OpenApi\Attributes命名空间。迁移路径建议为Classic → Hybrid → Spec。从 PHP 中生成文档编程式适合需要文档永远与代码同步的场景例如直接在控制器路由里动态生成。使用 Builder推荐入口?php require(vendor/autoload.php); $result (new \OpenApi\Builder()) -addSource([/path/to/project]) -build(); header(Content-Type: application/x-yaml); echo $result-toYaml();Builder是 src/Builder.php 中定义的统一入口addSource()可接受字符串路径、\SplFileInfo、\ReflectionClass甚至可迭代集合。构建结果封装在 src/Builder/Result.php 中提供了多种输出与诊断方法$result-toYaml(); // YAML 字符串 $result-toJson(); // JSON 字符串 $result-toArray(); // PHP 数组 $result-files(); // 扫描到的文件列表 $result-warnings(); // 校验告警列表 $result-errors(); // 校验错误列表 $result-isValid(); // 生成了文档且无错误时为 true $result-specification(); // 最终的 Specification 实例需要说明的是isValid()语义与命令行退出码一致——告警不影响有效性错误才使结果无效对应 Result.php 的实现。高级配置withGenerator 钩子需要配置自定义分析器、处理器、别名等进阶能力时使用withGenerator()钩子仅 classic 模式生效$result (new \OpenApi\Builder()) -addSource(/path/to/project) -setVersion(3.1.0) -withGenerator(function (\OpenApi\Generator $generator) { $generator-setConfig([operationId.hash false]); $generator-withProcessorPipeline(function ($pipeline) { $pipeline-add(new MyCustomProcessor()); }); }) -build();withGenerator()的钩子会在构建过程中、Generator实例创建后执行见 Builder.php 与 doBuildClassic。Spec 模式下直接传入 ReflectionClass在 spec/hybrid 模式下addSource()可以直接接收\ReflectionClass实例无需文件路径?php require(vendor/autoload.php); $result (new \OpenApi\Builder()) -setMode(\OpenApi\Builder\Mode::SPEC) -addSource([ new \ReflectionClass(App\Controllers\PetController::class), new \ReflectionClass(App\Models\Pet::class), ]) -build(); echo $result-toYaml();这一路径在 doBuildSpec 中通过sourceScanner-getReflectors()处理。直接使用 Generator仅 classic 模式?php require(vendor/autoload.php); $openapi (new \OpenApi\Generator())-generate([/path/to/project]); header(Content-Type: application/x-yaml); echo $openapi-toYaml();命令行使用生成静态文档openapi命令可以将文档输出为静态的 yaml/json 文件。先查看帮助./vendor/bin/openapi --help实际生成GenerateCommand 的实现示例./vendor/bin/openapi app -o openapi.yaml关键选项说明摘自-h输出与 GenerateCommand.php 的定义一致选项说明示例paths参数要扫描的源码路径必填可多个openapi app src/-c, --configGenerator/Augmenter 配置键随模式不同用-D查看-c operationId.hashfalse-D, --defaults显示默认配置openapi -D-o, --output输出文档的存储路径-o openapi.yaml-f, --format强制 yaml 或 json默认auto按扩展名推断-f json-e, --exclude排除路径-e vendor -e library/Zend-n, --pattern扫描文件的模式默认*.php-n /\.(phps|php)$/-b, --bootstrap引导加载 PHP 文件用于定义常量等-b config/constants.php-a, --add-processor注册额外的处理器-a AugmentTags-r, --remove-processor移除已有处理器-r AugmentTags--versionOpenAPI 版本--version 3.0.0-m, --mode处理模式 classic/hybrid/spec默认 classic-m spec-d, --debug显示额外的错误信息-d关于输出格式默认输出 YAML指定-o文件名后按扩展名推断格式.json输出 JSON-f可强制指定格式。-D选项会打印当前模式的默认配置classic 打印Generator配置、spec 打印 augmenter 管道配置、hybrid 二者兼有详见 GenerateCommand.php。Bootstrap 技巧-b选项在没有正确自动加载autoloading的情况下很有用。例如想用单个文件快速评估库时先让 swagger-php 引导预加载该文件PHP 的 reflection 代码才能检查到你的代码./vendor/bin/openapi -b my_file.php my_file.phpCLI 命令的入口脚本是 bin/openapi它负责加载 Composer 自动加载、构造 Symfony Console 应用并注册GenerateCommand同时会移除 Symfony 内置的--version与 OpenAPI 版本选项冲突和--no-interaction与-n模式选项冲突选项诊断日志走 stderr未指定-o时文档本体输出到 stdout。自动类型解析v6 新机制自6 版本起类型解析改用TypeInfoTypeResolver类。它在底层使用symfony/type-info库并借助radebatz/type-info-extras扩展能够处理复杂类型。由此swagger-php支持全部原生类型提示type-hints也支持通过 phpdoc 块声明的复杂泛型类型提示大大简化了 Schema 的定义。README 给出了一个关键结论以下两种写法现在等价——你可以手写Items/oneOf结构class MyClass { #[OAT\Property(items: new OAT\Items(oneOf: [ new OAT\Schema(type: SchemaOne::class), new OAT\Schema(type: SchemaTwo::class), ]))] public array $values; }也可以直接依赖 PHP 类型与 phpdoc 注解自动推导class MyClass { /** * var listSchemaOne|SchemaTwo */ public array $values; }从源码看TypeInfoTypeResolver 的doAugment()会先通过TypeResolver::resolve()得到SchemaType再据此填充 Schema 的type、format、minimum、maximum、items、additionalProperties、oneOf/allOf、properties与required等字段null可空性也会从 PHP 类型声明中推导可空属性会设置nullable。如果你不希望使用该机制可以用LegacyTypeResolver保留 v5 的旧行为——但它已被弃用将在未来版本移除。进一步阅读入门与属性/注解参考using-attributes、reference/annotations、reference/attributes生成文档的完整指南generating-openapi-documents处理模式对比与迁移路径modesSpec 属性详解spec-attributes、why-spec可直接运行的代码 对应 YAML 示例docs/examples含 petstore、polymorphism、using-interfaces、using-traits、webhooks 等专题相关项目docs/related-projects.md赞分享后端API设计文档代码生成【免费下载链接】swagger-phpA php swagger annotation and parsing library项目地址https://gitcode.com/gh_mirrors/sw/swagger-php点击查看免费下载相关推荐使用zircote/swagger-php生成OpenAPI文档指南使用zircote/swagger php生成OpenAPI文档指南 项目概述 zircote/swagger php是一个强大的PHP工具用于生成符合Ope后端API设计文档代码生成swagger-php 完全指南从零开始构建 OpenAPI 3.0/3.1 文档swagger php 完全指南从零开始构建 OpenAPI 3.0/3.1 文档 swagger php 是一个功能强大的 PHP 库专门用于通过 PHP后端API设计文档代码生成【免费下载】 Swagger-PHP 使用指南轻松为 PHP API 生成 OpenAPI 文档Swagger PHP 使用指南轻松为 PHP API 生成 OpenAPI 文档 项目概述 Swagger PHP 是一个强大的 PHP 工具能够直接从你后端API设计文档代码生成上一篇Nest-Winston 项目常见问题解决方案下一篇OpenPlayerJS 项目常见问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
