不能直接用 swagger-codegen 生成 codeigniter 的 api 文档，因其不解析 php 代码、不识别 ci 路由与控制器结构；必须使用 zircote/swagger-php ^4.9 扫描 phpdoc 注释生成 openapi 规范。
不能直接用 swagger-codegen 生成 CodeIgniter 的 API 文档。它不识别 CI 的控制器结构、路由逻辑和注释风格，跑出来的 JSON 基本是空的或报路径错误。真正能落地的只有 zircote/swagger-php 扫描 PHPDoc 注释这一条路。
为什么 swagger-codegen 对 CodeIgniter 失效
swagger-codegen 是为 OpenAPI 规范文件（swagger.json 或 openapi.yaml）服务的，它本身不解析 PHP 代码，只消费已有的规范。你给它一个 CI 项目目录，它既不会读 routes.php，也不会理解 $this->get() 或 RestController 的语义，更没法把 /** @OA\Get */ 这类注释转成结构化数据——那是 zircote/swagger-php 干的事。
常见失败现象：
- 执行
swagger-codegen generate -i ./application/controllers/ -l html报错Unable to read url或静默生成空文档 - 即使强行指定
-i指向某个假的 YAML 文件，生成的 HTML 里也全是占位符，没一个接口对应真实方法 - 试图用
swagger-codegen反向生成 CI 控制器模板？它输出的是 Laravel/Gin/Spring 风格代码，和 CI 的index_get()完全不兼容
必须用 zircote/swagger-php ^4.9 扫描注释
CI 3 和 CI 4 都没有内置 OpenAPI 解析器，zircote/swagger-php 是目前唯一能从 PHPDoc 提取结构化接口定义的主流工具。PHP 8.1+ 环境下必须用 ^4.9，低版本（如 2.x）不支持属性语法，会跳过所有 @OA\ 注释。
关键实操点：
- 安装命令只能是：
composer require zircote/swagger-php:^4.9（不是swagger-codegen） - 注释必须以
@OA\开头，不是旧版@SWG\，也不是单行写法（如/** @OA\Info(...) */） - 每个控制器类顶部必须有
@OA\Info或@OA\OpenApi，否则scan()返回空对象 -
@OA\Get、@OA\Post必须写在具体方法上，且path值要和 CI 路由实际匹配（比如 CI4 中routes/web.php写了$routes->get('api/users', 'UserController::index');，注释里就得写path="/api/users"）
scan() 路径必须指向真实 .php 文件所在目录
swagger\scan() 不接受通配符或动态常量拼接，它需要能 glob() 到一批带 .php 后缀的可读文件。写 APPPATH . 'controllers' 很容易失败，因为：
- CI3 的
APPPATH是application/，但控制器实际在application/controllers/；CI4 的APPPATH是app/，而控制器在app/Controllers/（注意大写 C） -
scan()不会递归子目录，如果控制器分散在Controllers/Api/和Controllers/Admin/，得分别扫描再合并 - 最稳写法是硬编码绝对路径，例如：
__DIR__ . '/../app/Controllers'（CI4），或__DIR__ . '/../../application/controllers'（CI3） - 扫描前先加一行
var_dump(glob($path . '/*.php'));，确认输出是非空数组
JSON 响应头和 Swagger UI 地址必须严格匹配
生成的 JSON 接口（如 /api/docs）若没设对响应头，Swagger UI 会卡在 “Loading…” 或报 TypeError: Failed to fetch，这不是跨域问题，而是 MIME 类型错误。
必须在输出 JSON 的控制器方法里手动加头：
header('Content-Type: application/json');
echo $openapi->toJson();
同时，Swagger UI 页面里的 url 字段必须填可访问的绝对地址，例如：
- 开发环境：
url: "http://localhost:8080/api/docs" - 线上环境：
url: "https://api.example.com/api/docs"（不能写相对路径"./api/docs"） - CI4 中若用了
force_https，这里也必须用https，否则浏览器会拦截混合内容
最容易被忽略的是：CI 的 output 类或 RestServer 中间件可能自动加了其他 Content-Type，导致你写的 header() 被覆盖。这时候得关掉自动格式化，或者用 exit() 强制终止后续流程。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
