openapi-generator-cli无法从带OpenAPI注解的PHP文件生成文档求助

核心问题 #

你混淆了两个工具的定位和使用流程，操作逻辑完全相反：

• zircote/swagger-php 负责从带OpenAPI注解的PHP代码中，导出JSON/YAML格式的规范文件，这正是你当前需要用到的工具
• openapi-generator-cli 的作用是反向操作：输入已有的JSON/YAML格式OpenAPI规范文件，输出对应语言的接口代码、SDK、静态文档等产物，不能直接识别PHP源码

正确操作步骤 #

1. 导出OpenAPI规范文件 #

直接使用你已安装的zircote/swagger-php自带的命令行工具，扫描你的控制器文件导出规范即可，执行命令：

./vendor/bin/openapi <path_to_LocationController> -o openapi.json

执行完成后你就能在当前目录下得到需要的openapi.json规范文件；如果需要YAML格式，只需要把输出文件名修改为openapi.yaml即可。

2. （可选）使用openapi-generator-cli处理规范 #

如果你后续需要基于生成的规范文件生成其他产物，比如客户端SDK、接口文档站点等，再调用openapi-generator-cli，传入第一步生成的规范文件即可，示例命令如下：

# 示例：生成静态HTML接口文档
openapi-generator-cli generate -g html2 -i ./openapi.json -o ./api-doc

你之前使用的-g php参数作用是生成PHP服务端骨架代码，不符合你当前的需求，无需使用。

报错原因说明 #

你之前直接将PHP源码作为输入传给openapi-generator-cli，该工具仅支持识别JSON/YAML格式的OpenAPI规范文件，因此抛出了输入格式错误的异常，和你代码里写的注解无关。

内容的提问来源于stack exchange，提问作者Skytiger