底层实现 (Under the hood)

处理流程 (Processing flow)

• Generator 会迭代处理给定的源文件（Symfony Finder、文件/目录列表等）。
• 配置好的分析器（AnalyserInterface）会读取文件并构建一个 Analysis 对象。默认（v4 及以后）是 ReflectionAnalyser。此外，还有一个 TokenAnalyser，它是 v3 版本的默认分析器。
• 旧版 TokenAnalyser 在 v5 中已被移除。
• Analysis 对象及其注解随后由配置好的处理器进行处理。
• 如果启用，将对分析结果/注解进行验证。
• 根 OpenApi 注解随后包含所有注解，并被序列化为 YAML/JSON。

上下文 (Context)

每个注解都与一个唯一的 Context 实例相关联。它包含了由解析器/分析器收集到的关于找到注解的 PHP 上下文的详细信息。

通常会有一个处理器使用这些数据来增强/丰富注解。

收集的数据示例：

• 类/接口/特性/枚举名称
• 属性名称
• docblock 类型或原生类型提示
• 文件名和行号

分析 (Analysis)

包含所有检测到的注解和其他相关的元数据。

它使用一个 SplObjectStorage 实例来存储解析后的注解。

文档 (Documentation)

本文档是使用 VitePress 生成的。

安装

cd docs
npm install

工作流程

1. 编辑 docs 文件夹中的 .md 文件。
2. 更新注解/属性的 PHP docblocks。
3. 这些内容将在发布时提取到 reference 部分。
4. 运行 composer docs:build 检查是否有任何错误。
5. 运行 composer docs:dev 在本地测试生成的文档（localhost:3000）。
6. 创建 PR 并更新 master 分支。
7. 手动触发 gh-pages 工作流来更新在线文档。

最后一步需要在 zircote/swagger-php 上拥有提交权限。