后端API设计文档代码生成【免费下载链接】swagger-phpA php swagger annotation and parsing library项目地址https://gitcode.com/gh_mirrors/sw/swagger-php点击查看免费下载swagger-php是一款从 PHP 源码中提取 API 元数据、并将其转换为机器可读的 OpenAPI 文档YAML/JSON的库。它的核心设计是把文档写在代码旁边通过 docblock 注解Annotations或 PHP 8.1 属性Attributes在类、方法、属性等结构元素上直接描述接口再借助命令行工具或 PHP API 一键生成规范文档从而让 API 文档与实现始终同步。读完本文你将掌握 swagger-php 的安装方式、两种标注语法、三种处理模式Classic / Hybrid / Spec以及 CLI 与Builder的完整用法。什么是 swagger-phpswagger-php是一个从 PHP 源代码文件中提取 API 元数据的库composer.json 中的描述为Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations。其工作方式的核心思路是在应用中与业务代码紧邻的位置添加swagger-php的 Annotations注解 或 Attributes属性这些标注包含关于 API 的细节信息随后swagger-php将它们转换为机器可读的 OpenAPI 文档支持 OpenAPI 3.0、3.1、3.2 三个版本。由于 API 文档与对应源代码存放在同一个文件中所有细节都可以在一处修改这让文档保持最新变得非常简单——改代码的同时就改了文档不存在文档滞后于实现的问题。标注Annotatingvs 注解Annotations文档中特意区分了两个容易混淆的概念当我们谈论标注你的代码annotating时指的是向代码库添加元数据这一行为。这既可以通过添加Annotationsdocblock 注解也可以通过添加AttributesPHP 属性来完成。也就是说Annotating 是动作Annotations 是其中一种具体语法。在 swagger-php 语境下用注解标注代码可能同时指代两者。环境要求使用swagger-php要求最低 PHP 8.2。这一要求同时体现在 composer.json 的require: { php: 8.2 }中。此外依赖中已包含nikic/php-parser、phpstan/phpdoc-parser、psr/log、symfony/console、symfony/finder、symfony/yaml等库。安装按项目安装官方推荐使用 Composer 将 swagger-php 加入项目composer require zircote/swagger-php安装后项目vendor/bin下会出现openapi命令行工具composer.json的bin: [bin/openapi]声明了该可执行文件。全局安装也可以使用 Composer 的global参数进行全局安装composer global require zircote/swagger-php::: warning PATH 变量 全局安装后需要将~/.composer/vendor/bin目录加入当前环境的 PATHopenapi可执行文件才能被系统找到。 :::可选依赖doctrine/annotations从版本 4.8 起doctrine annotations 库变为可选默认不再安装。如果你的代码使用 docblock 注解需要手动安装composer require doctrine/annotations由于 doctrine 注解库后续将被弃用官方建议尽可能使用 PHP Attributes。可选依赖type-info-extras类型解析器从 5.5 版本起swagger-php 引入了一个新的类型解析器用于确定属性及其他带 schema 的元素的 schema 类型。默认使用自定义的LegacyTypeResolver如果你运行在 PHP 8.2 及以上可以使用TypeInfoTypeResolver底层依赖symfony/type-info可处理复杂类型。该包是可选依赖需要手动安装composer require radebatz/type-info-extras::: warning 附加依赖 安装radebatz/type-info-extras会同时把symfony/type-info作为依赖引入。 :::用两种语法标注代码swagger-php 支持两种标注方式docblock 注解Annotations与PHP 属性Attributes。二者最终生成的结果一致但 Attributes 是推荐方式Annotations 已标记为弃用deprecated可能在未来版本中移除。Annotationsdocblock 注解Annotations 是包含 doctrine 风格注解 的 PHP 注释docblock。随着 PHP 8.1 引入对 Attributes 的支持注解在 favor of attributes 的背景下被弃用。命名空间所有注解都位于OpenApi\Annotations命名空间。使用命名空间别名可以简化输入并提高可读性use OpenApi\Annotations as OA; /** * OA\Info(...) */从严格意义上讲由于 Annotations 本质上是 PHP 注释use OpenApi\Annotations as OA;并非必须但 doctrine 对别名是否有效相当挑剔。好消息是swagger-php会自动注册OA别名因此无需额外工作即可直接使用OA快捷方式。示例?php use OpenApi\Annotations as OA; /** * OA\Info(titleMy First API, version0.1) */ class OpenApi {} class MyController { /** * OA\Get( * path/api/resource.json, * OA\Response(response200, descriptionAn example resource) * ) */ public function resource() { // ... } }转义双引号在 docblock 注解中双引号可以通过双写而非使用\来转义OA\Schema( titleRequest, schemaRequest, example{ configuration:{formConfig:123} } )数组与对象Doctrine 注解支持数组但使用{和}而非[和]。对象同样使用{和}且属性名需要用包裹。不要这样写虽然能工作但大多数对象都有一个与属性同名的注解类如contact对应OA\Contact/** * OA\Info( * titleMy first API, * version1.0.0, * contact{ * email: supportexample.com * } * ) */推荐这样写/** * OA\Info( * titleMy first API, * version1.0.0, * OA\Contact( * emailsupportexample.com * ) * ) */使用嵌套注解还有一个额外好处会触发校验。当你拼错属性名或遗漏必填属性时会触发 PHP 警告。例如写emialsupportexample.comswagger-php 会生成类似Unexpected field emial for OA\Contact(), expecting name, email, ...的提示。放置多个同类型注解会得到一个对象数组。对于对象键由与注解同名的字段定义OA\Response中的response、OA\Property中的property等。/** * OA\Get( * path/products, * summarylist products, * OA\Response( * response200, * descriptionA list with products * ), * OA\Response( * responsedefault, * descriptionan unexpected error * ) * ) */生成结果openapi: 3.0.0 paths: /products: get: summary: list products responses: 200: description: A list with products default: description: an unexpected error使用常量你可以在 doctrine 注解中使用常量define(API_HOST, ($env production) ? example.com : localhost);/** * OA\Server(urlAPI_HOST) */::: tip 提示 使用 CLI 时如果常量定义在单独的文件中可能需要通过--bootstrap选项先加载该文件openapi --bootstrap constants.php:::AttributesPHP 属性PHP Attributes 是标注代码的首选方式。命名空间所有属性都位于OpenApi\Attributes命名空间use OpenApi\Attributes as OA; #[OA\Info(/*...*/)]嵌套Nesting与注解类似属性可以位于顶层也可以嵌套。不过如果不存在歧义属性可以放在同一层级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()这一层。最小可运行示例Attributes 版来自 docs/snippets/minimal_api_at.php?php namespace Openapi\Snippets\MinimalApi; use OpenApi\Attributes as OA; #[OA\Info(title: My First API, version: 0.1)] class OpenApi { } class MyController { #[OA\Get(path: /api/data.json, operationId: getData)] #[OA\Response(response: 200, description: The data)] public function getResource() { // ... } }对应注解版docs/snippets/minimal_api_an.php与 spec 属性版docs/snippets/minimal_api_spec.php产出相同的 OpenAPI 文档。最小必需标注OpenAPI 规范定义了一份合法文档所需的最小信息集合主要包括 API 的通用信息如name、version以及至少一个端点端点又需要路径和至少一个响应。一个只有单个端点的最小 API 生成结果如下完整输出见 docs/snippets/minimal_api-3.1.0.yamlopenapi: 3.1.0 info: title: My First API version: 0.1 paths: /api/data.json: get: operationId: getData responses: 200: description: The data::: warning 标注放在哪里 属性与注解可以放在代码库的任何位置只要它们与结构性元素类、方法、属性等关联即可。实际上只要是 PHP 反射reflection能找到的位置都可以放置标注。 :::另外你会发现生成的文档中有些元素是 swagger-php 在缺失时自动补充的主要是OA\OpenApi、OA\Components和OA\PathItem。它们由 OpenAPI 规范定义用于分组并让生成的 JSON/YAML 更有结构。除非有特殊原因你不需要手动添加它们。标注应紧邻应用代码放置这样你可以直接在所描述代码的旁边看到标注也更便于保持二者同步。swagger-php会扫描整个项目把所有元数据合并进一个OA\OpenApi注解中。::: warning 注意 从 swagger-php v4 起所有属性/注解必须与结构性元素class、method、parameter或enum关联。 :::生成 OpenAPI 文档使用命令行swagger-php 自带命令行工具./vendor/bin/openapi可用来生成 OpenAPI 文档 ./vendor/bin/openapi app -o openapi.yaml::: tip 输出格式 默认输出格式为 YAML。如果通过--output或-o指定了文件名工具会根据文件扩展名判断格式。也可以使用--format强制指定格式。 :::--bootstrap-b选项在无法正常自动加载autoload时非常有用。例如你想用一个只含少量标注的单文件来评估该库此时告诉 swagger-php 先 bootstrap预加载该文件可以确保 PHP 的反射代码能够检查到你的代码 ./vendor/bin/openapi -b my_file.php my_file.php使用-h可以查看所有可用选项 ./vendor/bin/openapi -h Description: Generate OpenAPI documentation Usage: openapi [options] [--] paths... Arguments: paths Source path(s) to scan Options: -c, --configCONFIG Generator/Augmenter config; keys differ per mode, see -D (e.g. -c operationId.hashfalse) (multiple values allowed) -D, --defaults Show default config -o, --outputOUTPUT Path to store the generated documentation (e.g. -o openapi.yaml) -f, --formatFORMAT Force yaml or json [default: auto] -e, --excludeEXCLUDE Exclude path(s) (e.g. -e vendor -e library/Zend) (multiple values allowed) -n, --patternPATTERN Pattern of files to scan (e.g. -n /\.(phps|php)$/) [default: *.php] -b, --bootstrapBOOTSTRAP Bootstrap php file(s) for defining constants, etc. (e.g. -b config/constants.php) (multiple values allowed) -a, --add-processorADD-PROCESSOR Register an additional processor (multiple values allowed) -r, --remove-processorREMOVE-PROCESSOR Remove an existing processor (multiple values allowed) --versionVERSION The OpenAPI version -m, --modeMODE Set mode classic, hybrid or spec [default: classic] -d, --debug Show additional error information -h, --help Display help for the given command. When no command is given display help for the list command --silent Do not output any message -q, --quiet Only errors are displayed. All other output is suppressed --ansi|--no-ansi Force (or disable --no-ansi) ANSI output -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug这些选项的定义可在 src/Console/GenerateCommand.php 中直接查看例如paths为必填参数--mode支持classic、hybrid、spec三值默认classic。使用 PHP 代码Builder根据使用场景也可以用 PHP 代码以更动态的方式生成 OpenAPI 文档。Builder类是官方推荐的 PHP 入口点见 src/Builder.php?php require(vendor/autoload.php); $result (new \OpenApi\Builder()) -addSource(/path/to/project) -build(); header(Content-Type: application/x-yaml); echo $result-toYaml();Result对象见 src/Builder/Result.php提供对生成规范的多种格式访问以及被扫描文件列表、生成期间收集到的校验警告或错误$result-toYaml(); // YAML string $result-toJson(); // JSON string $result-toArray(); // PHP array $result-files(); // list of scanned files $result-warnings(); // validation warnings $result-errors(); // validation errors $result-isValid(); // true if spec was generated and no errors were reported $result-specification(); // the final Specification instance如果需要高级的 Generator 配置自定义 analyser、processor、别名等可以使用withGenerator()钩子$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();使用 Generator 直接生成仅 Classic 模式Generator类也可以直接使用仅限 classic 模式?php require(vendor/autoload.php); $openapi (new \OpenApi\Generator())-generate([/path/to/project]); header(Content-Type: application/x-yaml); echo $openapi-toYaml();更多编程 API 细节可参考 docs/reference/index.md。三种处理模式swagger-php 支持三种处理模式它们控制源码如何被转换为 OpenAPI 文档每种模式使用不同的内部流水线pipeline。ClassicHybridSpec状态稳定StableBetaBeta属性OpenApi\AttributesOpenApi\AttributesOpenApi\Spec注解支持支持不支持流水线Generator → ProcessorsAssembler → Resolver → HybridBridge → Augmenters → CompilerAssembler → Resolver → Augmenters → CompilerClassic默认Classic 模式扫描源码文件中的OpenApi\Attributes以及遗留的OpenApi\Annotations并通过Generator及其 processor 链构建 OpenAPI 文档use OpenApi\Builder; $result (new Builder()) -addSource(src/) -build(); $result-toYaml();Classic 模式通过withGenerator()提供完整的GeneratorAPI包括自定义 processor、analyser 和配置选项。SpecbetaSpec 模式从零开始重新实现流水线使用OpenApi\Spec命名空间的属性引入了以下特性类型化 DTO属性是带有构造器提升属性的简单数据容器Slot-map 嵌套显式的merge()/contained()映射取代了基于反射的嵌套分组 augmenter三阶段流水线resolve → reduce → augment顺序显式版本感知编译器针对 OpenAPI 3.0、3.1、3.2 的独立编译器。use OpenApi\Builder; use OpenApi\Builder\Mode; $result (new Builder()) -setMode(Mode::SPEC) -addSource(src/) -build(); $result-toYaml();Spec 模式使用OpenApi\Spec命名空间use OpenApi\Spec as OA;完整指南见 docs/guide/spec-attributes.md。::: warning Beta Spec 模式功能大体完整但仍处于 beta 阶段。属性 API 可能会根据反馈演进然后才在未来的主版本中成为默认。 :::HybridbetaHybrid 模式使用经典的Generator进行扫描因此现有OpenApi\Attributes代码无需改动即可工作随后通过 HybridBridge 将结果桥接到 spec 流水线的 augmenter 和 compiler 中。这让你无需重写任何属性代码就能获得 augmenter 流水线和版本感知编译能力use OpenApi\Builder; use OpenApi\Builder\Mode; $result (new Builder()) -setMode(Mode::HYBRID) -addSource(src/) -build(); $result-toYaml();Hybrid 模式是现有项目逐步迁移到新流水线的推荐过渡路径。::: warning 声明 Hybrid 模式在重度定制的项目如NelmioApiDocBundle或添加自定义 processor 的项目中无法工作。 :::切换模式CLI./vendor/bin/openapi src/ --mode spec -o openapi.yaml ./vendor/bin/openapi src/ --mode hybrid -o openapi.yamlPHPuse OpenApi\Builder; use OpenApi\Builder\Mode; $builder-setMode(Mode::SPEC); // or: $builder-setMode(spec);行为差异各模式的目标是从相同源码产出等价输出但在可接受输入与可配置性上有所不同行为ClassicHybridSpec注解支持/** OA\... */支持支持不支持MergeJsonContent/MergeXmlContent支持支持支持通过OA\MediaType\JsonProcessor 链withGenerator()支持仅扫描MergeJsonContent/MergeXmlContent不支持ResolverwithResolver()不支持支持默认Resolver\Reflection支持默认Resolver\ReflectionAugmenter 流水线withAugmenters()不支持支持支持ContributionswithSpecification()不支持支持支持版本感知编译不支持单一序列化器支持支持未引用组件保留移除并输出 notice移除并输出 notice-c/-D键Processors、generator.*Augmenters、generator.*AugmentersClassic 模式仅在要求时-c cleanUnusedComponents.enabledtrue移除未引用组件。Hybrid 和 spec 默认移除它们并在 notice 级别记录数量。-c cleanup.enabledfalse可以保留它们PHP 写法use OpenApi\Augmenter; use OpenApi\Utils\Pipeline; $builder-withAugmenters(fn (Pipeline $pipeline) $pipeline-get(Augmenter\Cleanup::class)-setEnabled(false));详见 docs/reference/augmenters.md 中的Cleanup选项。推荐迁移路径Classic → Hybrid改为setMode(Mode::HYBRID)。无需任何代码改动augmenter 流水线即可用。输出保持不变仅有两处例外无任何路径引用的组件会被移除包括仅为客户端代码生成而保留的 schema-c接受 augmenter 键而非 processor 键generator.*除外。--mode hybrid -D src可列出它们。Hybrid → Spec写新代码时使用OpenApi\Spec属性现有OpenApi\Attributes代码通过 hybrid 模式继续工作。spec 属性并非 classic 的一对一改名可复用属性采用单一的component:键而 classic 按自身类型拼写键schema:、parameter:、request:、securityScheme:。完全 Spec当所有代码都使用OpenApi\Spec属性后切换到setMode(Mode::SPEC)。::: tip 版本时间线v6spec 与 hybrid 以可选的 beta 形态发布Classic 仍是默认。v7hybrid 成为默认模式Classic 仍可用。setMode()及所有 classic 代码被弃用。v8移除 classic 与setMode()Spec 成为默认。Spec 属性移动到OpenApi\Attributes。对已按OpenApi\Spec编写的代码迁移只需每文件一行use修改从 classic 迁移而来的组件键也需改名。 :::底层处理流程在 docs/guide/under-the-hood.md 中文档揭示了 Classic 流水线的处理流程Generator遍历给定源码SymfonyFinder、文件/目录列表等配置的 analyserAnalyserInterface读取文件并构建Analysis对象默认是ReflectionAnalyserAnalysis对象及其注解随后由配置的 processors 处理如果启用分析/注解会被校验根OpenApi注解包含所有注解并被序列化为 YAML/JSON。每个注解都关联一个唯一的Context实例包含 parser/analyser 收集到的 PHP 上下文信息例如类/接口/trait/enum 名称、属性名、docblock 或原生类型提示、文件名与行号。通常会有 processor 利用这些数据来增强注解。Analysis包含所有检测到的注解与其他相关元数据内部使用SplObjectStorage存储解析出的注解。在 Spec/Hybrid 模式下见 src/Builder.php 的doBuildSpec()流程变为SourceScanner扫描文件 →AttributeFactory/TokenScanner定位类 →Assembler::collect()收集属性 → 构建Specification→ComponentName::normalise()规范化组件键 →Resolver解析$ref→ augmenter 流水线Inheritance、Names、Enums、Shortcuts、PathItems、Types、Refs、Parameters、Merge、PathFilter、Cleanup、MediaTypes、Docblocks、OperationIds、Tags、EnumDescriptions 等→ 依据版本选择对应编译器OpenApi30Compiler/OpenApi31Compiler/OpenApi32Compiler→validate()compile()产出结果。从 Hello World 到实战回到 swagger-php 的核心理念——文档与代码同源。一个典型的落地流程是composer require zircote/swagger-php安装在Info全局信息、Get/Post等 Operation端点、Schema/Property数据模型、Response响应等位置添加标注用./vendor/bin/openapi src -o openapi.yaml生成文档或通过Builder在运行时动态输出配合 Swagger UI 或 Scalar 等工具探索和交互你的 API。更多深入主题可继续阅读Annotations 详解 与 Attributes 详解生成 OpenAPI 文档处理模式对比Spec 属性使用指南最小必需标注参考文档 与 参考注解/属性清单赞分享后端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 使用指南轻松为 PHP API 生成 OpenAPI 文档Swagger PHP 使用指南轻松为 PHP API 生成 OpenAPI 文档 项目概述 Swagger PHP 是一个强大的 PHP 工具能够直接从你后端API设计文档代码生成DVWA API 模块 OpenAPI 文档生成指南基于 swagger-php 属性注解与 Composer 的实践DVWA API 模块 OpenAPI 文档生成指南基于 swagger php 属性注解与 Composer 的实践 导读 本文聚焦 DVWADamn V应用安全渗透测试教育上一篇FanControl风扇控制软件从噪音困扰到静音享受的完整指南下一篇英雄联盟玩家的智能助手League Akari 本地化工具箱完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/13 8:32:52 · 阅读 1.2k swagger-php 入门：在 PHP 源码中标注并生成 OpenAPI 文档
后端API设计文档代码生成【免费下载链接】swagger-phpA php swagger annotation and parsing library项目地址https://gitcode.com/gh_mirrors/sw/swagger-php点击查看免费下载swagger-php是一款从 PHP 源码中提取 API 元数据、并将其转换为机器可读的 OpenAPI 文档YAML/JSON的库。它的核心设计是把文档写在代码旁边通过 docblock 注解Annotations或 PHP 8.1 属性Attributes在类、方法、属性等结构元素上直接描述接口再借助命令行工具或 PHP API 一键生成规范文档从而让 API 文档与实现始终同步。读完本文你将掌握 swagger-php 的安装方式、两种标注语法、三种处理模式Classic / Hybrid / Spec以及 CLI 与Builder的完整用法。什么是 swagger-phpswagger-php是一个从 PHP 源代码文件中提取 API 元数据的库composer.json 中的描述为Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations。其工作方式的核心思路是在应用中与业务代码紧邻的位置添加swagger-php的 Annotations注解 或 Attributes属性这些标注包含关于 API 的细节信息随后swagger-php将它们转换为机器可读的 OpenAPI 文档支持 OpenAPI 3.0、3.1、3.2 三个版本。由于 API 文档与对应源代码存放在同一个文件中所有细节都可以在一处修改这让文档保持最新变得非常简单——改代码的同时就改了文档不存在文档滞后于实现的问题。标注Annotatingvs 注解Annotations文档中特意区分了两个容易混淆的概念当我们谈论标注你的代码annotating时指的是向代码库添加元数据这一行为。这既可以通过添加Annotationsdocblock 注解也可以通过添加AttributesPHP 属性来完成。也就是说Annotating 是动作Annotations 是其中一种具体语法。在 swagger-php 语境下用注解标注代码可能同时指代两者。环境要求使用swagger-php要求最低 PHP 8.2。这一要求同时体现在 composer.json 的require: { php: 8.2 }中。此外依赖中已包含nikic/php-parser、phpstan/phpdoc-parser、psr/log、symfony/console、symfony/finder、symfony/yaml等库。安装按项目安装官方推荐使用 Composer 将 swagger-php 加入项目composer require zircote/swagger-php安装后项目vendor/bin下会出现openapi命令行工具composer.json的bin: [bin/openapi]声明了该可执行文件。全局安装也可以使用 Composer 的global参数进行全局安装composer global require zircote/swagger-php::: warning PATH 变量 全局安装后需要将~/.composer/vendor/bin目录加入当前环境的 PATHopenapi可执行文件才能被系统找到。 :::可选依赖doctrine/annotations从版本 4.8 起doctrine annotations 库变为可选默认不再安装。如果你的代码使用 docblock 注解需要手动安装composer require doctrine/annotations由于 doctrine 注解库后续将被弃用官方建议尽可能使用 PHP Attributes。可选依赖type-info-extras类型解析器从 5.5 版本起swagger-php 引入了一个新的类型解析器用于确定属性及其他带 schema 的元素的 schema 类型。默认使用自定义的LegacyTypeResolver如果你运行在 PHP 8.2 及以上可以使用TypeInfoTypeResolver底层依赖symfony/type-info可处理复杂类型。该包是可选依赖需要手动安装composer require radebatz/type-info-extras::: warning 附加依赖 安装radebatz/type-info-extras会同时把symfony/type-info作为依赖引入。 :::用两种语法标注代码swagger-php 支持两种标注方式docblock 注解Annotations与PHP 属性Attributes。二者最终生成的结果一致但 Attributes 是推荐方式Annotations 已标记为弃用deprecated可能在未来版本中移除。Annotationsdocblock 注解Annotations 是包含 doctrine 风格注解 的 PHP 注释docblock。随着 PHP 8.1 引入对 Attributes 的支持注解在 favor of attributes 的背景下被弃用。命名空间所有注解都位于OpenApi\Annotations命名空间。使用命名空间别名可以简化输入并提高可读性use OpenApi\Annotations as OA; /** * OA\Info(...) */从严格意义上讲由于 Annotations 本质上是 PHP 注释use OpenApi\Annotations as OA;并非必须但 doctrine 对别名是否有效相当挑剔。好消息是swagger-php会自动注册OA别名因此无需额外工作即可直接使用OA快捷方式。示例?php use OpenApi\Annotations as OA; /** * OA\Info(titleMy First API, version0.1) */ class OpenApi {} class MyController { /** * OA\Get( * path/api/resource.json, * OA\Response(response200, descriptionAn example resource) * ) */ public function resource() { // ... } }转义双引号在 docblock 注解中双引号可以通过双写而非使用\来转义OA\Schema( titleRequest, schemaRequest, example{ configuration:{formConfig:123} } )数组与对象Doctrine 注解支持数组但使用{和}而非[和]。对象同样使用{和}且属性名需要用包裹。不要这样写虽然能工作但大多数对象都有一个与属性同名的注解类如contact对应OA\Contact/** * OA\Info( * titleMy first API, * version1.0.0, * contact{ * email: supportexample.com * } * ) */推荐这样写/** * OA\Info( * titleMy first API, * version1.0.0, * OA\Contact( * emailsupportexample.com * ) * ) */使用嵌套注解还有一个额外好处会触发校验。当你拼错属性名或遗漏必填属性时会触发 PHP 警告。例如写emialsupportexample.comswagger-php 会生成类似Unexpected field emial for OA\Contact(), expecting name, email, ...的提示。放置多个同类型注解会得到一个对象数组。对于对象键由与注解同名的字段定义OA\Response中的response、OA\Property中的property等。/** * OA\Get( * path/products, * summarylist products, * OA\Response( * response200, * descriptionA list with products * ), * OA\Response( * responsedefault, * descriptionan unexpected error * ) * ) */生成结果openapi: 3.0.0 paths: /products: get: summary: list products responses: 200: description: A list with products default: description: an unexpected error使用常量你可以在 doctrine 注解中使用常量define(API_HOST, ($env production) ? example.com : localhost);/** * OA\Server(urlAPI_HOST) */::: tip 提示 使用 CLI 时如果常量定义在单独的文件中可能需要通过--bootstrap选项先加载该文件openapi --bootstrap constants.php:::AttributesPHP 属性PHP Attributes 是标注代码的首选方式。命名空间所有属性都位于OpenApi\Attributes命名空间use OpenApi\Attributes as OA; #[OA\Info(/*...*/)]嵌套Nesting与注解类似属性可以位于顶层也可以嵌套。不过如果不存在歧义属性可以放在同一层级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()这一层。最小可运行示例Attributes 版来自 docs/snippets/minimal_api_at.php?php namespace Openapi\Snippets\MinimalApi; use OpenApi\Attributes as OA; #[OA\Info(title: My First API, version: 0.1)] class OpenApi { } class MyController { #[OA\Get(path: /api/data.json, operationId: getData)] #[OA\Response(response: 200, description: The data)] public function getResource() { // ... } }对应注解版docs/snippets/minimal_api_an.php与 spec 属性版docs/snippets/minimal_api_spec.php产出相同的 OpenAPI 文档。最小必需标注OpenAPI 规范定义了一份合法文档所需的最小信息集合主要包括 API 的通用信息如name、version以及至少一个端点端点又需要路径和至少一个响应。一个只有单个端点的最小 API 生成结果如下完整输出见 docs/snippets/minimal_api-3.1.0.yamlopenapi: 3.1.0 info: title: My First API version: 0.1 paths: /api/data.json: get: operationId: getData responses: 200: description: The data::: warning 标注放在哪里 属性与注解可以放在代码库的任何位置只要它们与结构性元素类、方法、属性等关联即可。实际上只要是 PHP 反射reflection能找到的位置都可以放置标注。 :::另外你会发现生成的文档中有些元素是 swagger-php 在缺失时自动补充的主要是OA\OpenApi、OA\Components和OA\PathItem。它们由 OpenAPI 规范定义用于分组并让生成的 JSON/YAML 更有结构。除非有特殊原因你不需要手动添加它们。标注应紧邻应用代码放置这样你可以直接在所描述代码的旁边看到标注也更便于保持二者同步。swagger-php会扫描整个项目把所有元数据合并进一个OA\OpenApi注解中。::: warning 注意 从 swagger-php v4 起所有属性/注解必须与结构性元素class、method、parameter或enum关联。 :::生成 OpenAPI 文档使用命令行swagger-php 自带命令行工具./vendor/bin/openapi可用来生成 OpenAPI 文档 ./vendor/bin/openapi app -o openapi.yaml::: tip 输出格式 默认输出格式为 YAML。如果通过--output或-o指定了文件名工具会根据文件扩展名判断格式。也可以使用--format强制指定格式。 :::--bootstrap-b选项在无法正常自动加载autoload时非常有用。例如你想用一个只含少量标注的单文件来评估该库此时告诉 swagger-php 先 bootstrap预加载该文件可以确保 PHP 的反射代码能够检查到你的代码 ./vendor/bin/openapi -b my_file.php my_file.php使用-h可以查看所有可用选项 ./vendor/bin/openapi -h Description: Generate OpenAPI documentation Usage: openapi [options] [--] paths... Arguments: paths Source path(s) to scan Options: -c, --configCONFIG Generator/Augmenter config; keys differ per mode, see -D (e.g. -c operationId.hashfalse) (multiple values allowed) -D, --defaults Show default config -o, --outputOUTPUT Path to store the generated documentation (e.g. -o openapi.yaml) -f, --formatFORMAT Force yaml or json [default: auto] -e, --excludeEXCLUDE Exclude path(s) (e.g. -e vendor -e library/Zend) (multiple values allowed) -n, --patternPATTERN Pattern of files to scan (e.g. -n /\.(phps|php)$/) [default: *.php] -b, --bootstrapBOOTSTRAP Bootstrap php file(s) for defining constants, etc. (e.g. -b config/constants.php) (multiple values allowed) -a, --add-processorADD-PROCESSOR Register an additional processor (multiple values allowed) -r, --remove-processorREMOVE-PROCESSOR Remove an existing processor (multiple values allowed) --versionVERSION The OpenAPI version -m, --modeMODE Set mode classic, hybrid or spec [default: classic] -d, --debug Show additional error information -h, --help Display help for the given command. When no command is given display help for the list command --silent Do not output any message -q, --quiet Only errors are displayed. All other output is suppressed --ansi|--no-ansi Force (or disable --no-ansi) ANSI output -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug这些选项的定义可在 src/Console/GenerateCommand.php 中直接查看例如paths为必填参数--mode支持classic、hybrid、spec三值默认classic。使用 PHP 代码Builder根据使用场景也可以用 PHP 代码以更动态的方式生成 OpenAPI 文档。Builder类是官方推荐的 PHP 入口点见 src/Builder.php?php require(vendor/autoload.php); $result (new \OpenApi\Builder()) -addSource(/path/to/project) -build(); header(Content-Type: application/x-yaml); echo $result-toYaml();Result对象见 src/Builder/Result.php提供对生成规范的多种格式访问以及被扫描文件列表、生成期间收集到的校验警告或错误$result-toYaml(); // YAML string $result-toJson(); // JSON string $result-toArray(); // PHP array $result-files(); // list of scanned files $result-warnings(); // validation warnings $result-errors(); // validation errors $result-isValid(); // true if spec was generated and no errors were reported $result-specification(); // the final Specification instance如果需要高级的 Generator 配置自定义 analyser、processor、别名等可以使用withGenerator()钩子$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();使用 Generator 直接生成仅 Classic 模式Generator类也可以直接使用仅限 classic 模式?php require(vendor/autoload.php); $openapi (new \OpenApi\Generator())-generate([/path/to/project]); header(Content-Type: application/x-yaml); echo $openapi-toYaml();更多编程 API 细节可参考 docs/reference/index.md。三种处理模式swagger-php 支持三种处理模式它们控制源码如何被转换为 OpenAPI 文档每种模式使用不同的内部流水线pipeline。ClassicHybridSpec状态稳定StableBetaBeta属性OpenApi\AttributesOpenApi\AttributesOpenApi\Spec注解支持支持不支持流水线Generator → ProcessorsAssembler → Resolver → HybridBridge → Augmenters → CompilerAssembler → Resolver → Augmenters → CompilerClassic默认Classic 模式扫描源码文件中的OpenApi\Attributes以及遗留的OpenApi\Annotations并通过Generator及其 processor 链构建 OpenAPI 文档use OpenApi\Builder; $result (new Builder()) -addSource(src/) -build(); $result-toYaml();Classic 模式通过withGenerator()提供完整的GeneratorAPI包括自定义 processor、analyser 和配置选项。SpecbetaSpec 模式从零开始重新实现流水线使用OpenApi\Spec命名空间的属性引入了以下特性类型化 DTO属性是带有构造器提升属性的简单数据容器Slot-map 嵌套显式的merge()/contained()映射取代了基于反射的嵌套分组 augmenter三阶段流水线resolve → reduce → augment顺序显式版本感知编译器针对 OpenAPI 3.0、3.1、3.2 的独立编译器。use OpenApi\Builder; use OpenApi\Builder\Mode; $result (new Builder()) -setMode(Mode::SPEC) -addSource(src/) -build(); $result-toYaml();Spec 模式使用OpenApi\Spec命名空间use OpenApi\Spec as OA;完整指南见 docs/guide/spec-attributes.md。::: warning Beta Spec 模式功能大体完整但仍处于 beta 阶段。属性 API 可能会根据反馈演进然后才在未来的主版本中成为默认。 :::HybridbetaHybrid 模式使用经典的Generator进行扫描因此现有OpenApi\Attributes代码无需改动即可工作随后通过 HybridBridge 将结果桥接到 spec 流水线的 augmenter 和 compiler 中。这让你无需重写任何属性代码就能获得 augmenter 流水线和版本感知编译能力use OpenApi\Builder; use OpenApi\Builder\Mode; $result (new Builder()) -setMode(Mode::HYBRID) -addSource(src/) -build(); $result-toYaml();Hybrid 模式是现有项目逐步迁移到新流水线的推荐过渡路径。::: warning 声明 Hybrid 模式在重度定制的项目如NelmioApiDocBundle或添加自定义 processor 的项目中无法工作。 :::切换模式CLI./vendor/bin/openapi src/ --mode spec -o openapi.yaml ./vendor/bin/openapi src/ --mode hybrid -o openapi.yamlPHPuse OpenApi\Builder; use OpenApi\Builder\Mode; $builder-setMode(Mode::SPEC); // or: $builder-setMode(spec);行为差异各模式的目标是从相同源码产出等价输出但在可接受输入与可配置性上有所不同行为ClassicHybridSpec注解支持/** OA\... */支持支持不支持MergeJsonContent/MergeXmlContent支持支持支持通过OA\MediaType\JsonProcessor 链withGenerator()支持仅扫描MergeJsonContent/MergeXmlContent不支持ResolverwithResolver()不支持支持默认Resolver\Reflection支持默认Resolver\ReflectionAugmenter 流水线withAugmenters()不支持支持支持ContributionswithSpecification()不支持支持支持版本感知编译不支持单一序列化器支持支持未引用组件保留移除并输出 notice移除并输出 notice-c/-D键Processors、generator.*Augmenters、generator.*AugmentersClassic 模式仅在要求时-c cleanUnusedComponents.enabledtrue移除未引用组件。Hybrid 和 spec 默认移除它们并在 notice 级别记录数量。-c cleanup.enabledfalse可以保留它们PHP 写法use OpenApi\Augmenter; use OpenApi\Utils\Pipeline; $builder-withAugmenters(fn (Pipeline $pipeline) $pipeline-get(Augmenter\Cleanup::class)-setEnabled(false));详见 docs/reference/augmenters.md 中的Cleanup选项。推荐迁移路径Classic → Hybrid改为setMode(Mode::HYBRID)。无需任何代码改动augmenter 流水线即可用。输出保持不变仅有两处例外无任何路径引用的组件会被移除包括仅为客户端代码生成而保留的 schema-c接受 augmenter 键而非 processor 键generator.*除外。--mode hybrid -D src可列出它们。Hybrid → Spec写新代码时使用OpenApi\Spec属性现有OpenApi\Attributes代码通过 hybrid 模式继续工作。spec 属性并非 classic 的一对一改名可复用属性采用单一的component:键而 classic 按自身类型拼写键schema:、parameter:、request:、securityScheme:。完全 Spec当所有代码都使用OpenApi\Spec属性后切换到setMode(Mode::SPEC)。::: tip 版本时间线v6spec 与 hybrid 以可选的 beta 形态发布Classic 仍是默认。v7hybrid 成为默认模式Classic 仍可用。setMode()及所有 classic 代码被弃用。v8移除 classic 与setMode()Spec 成为默认。Spec 属性移动到OpenApi\Attributes。对已按OpenApi\Spec编写的代码迁移只需每文件一行use修改从 classic 迁移而来的组件键也需改名。 :::底层处理流程在 docs/guide/under-the-hood.md 中文档揭示了 Classic 流水线的处理流程Generator遍历给定源码SymfonyFinder、文件/目录列表等配置的 analyserAnalyserInterface读取文件并构建Analysis对象默认是ReflectionAnalyserAnalysis对象及其注解随后由配置的 processors 处理如果启用分析/注解会被校验根OpenApi注解包含所有注解并被序列化为 YAML/JSON。每个注解都关联一个唯一的Context实例包含 parser/analyser 收集到的 PHP 上下文信息例如类/接口/trait/enum 名称、属性名、docblock 或原生类型提示、文件名与行号。通常会有 processor 利用这些数据来增强注解。Analysis包含所有检测到的注解与其他相关元数据内部使用SplObjectStorage存储解析出的注解。在 Spec/Hybrid 模式下见 src/Builder.php 的doBuildSpec()流程变为SourceScanner扫描文件 →AttributeFactory/TokenScanner定位类 →Assembler::collect()收集属性 → 构建Specification→ComponentName::normalise()规范化组件键 →Resolver解析$ref→ augmenter 流水线Inheritance、Names、Enums、Shortcuts、PathItems、Types、Refs、Parameters、Merge、PathFilter、Cleanup、MediaTypes、Docblocks、OperationIds、Tags、EnumDescriptions 等→ 依据版本选择对应编译器OpenApi30Compiler/OpenApi31Compiler/OpenApi32Compiler→validate()compile()产出结果。从 Hello World 到实战回到 swagger-php 的核心理念——文档与代码同源。一个典型的落地流程是composer require zircote/swagger-php安装在Info全局信息、Get/Post等 Operation端点、Schema/Property数据模型、Response响应等位置添加标注用./vendor/bin/openapi src -o openapi.yaml生成文档或通过Builder在运行时动态输出配合 Swagger UI 或 Scalar 等工具探索和交互你的 API。更多深入主题可继续阅读Annotations 详解 与 Attributes 详解生成 OpenAPI 文档处理模式对比Spec 属性使用指南最小必需标注参考文档 与 参考注解/属性清单赞分享后端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 使用指南轻松为 PHP API 生成 OpenAPI 文档Swagger PHP 使用指南轻松为 PHP API 生成 OpenAPI 文档 项目概述 Swagger PHP 是一个强大的 PHP 工具能够直接从你后端API设计文档代码生成DVWA API 模块 OpenAPI 文档生成指南基于 swagger-php 属性注解与 Composer 的实践DVWA API 模块 OpenAPI 文档生成指南基于 swagger php 属性注解与 Composer 的实践 导读 本文聚焦 DVWADamn V应用安全渗透测试教育上一篇FanControl风扇控制软件从噪音困扰到静音享受的完整指南下一篇英雄联盟玩家的智能助手League Akari 本地化工具箱完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考