Download the PHP package kontirol/apidoc without Composer
On this page you can find all versions of the php package kontirol/apidoc. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download kontirol/apidoc
More information about kontirol/apidoc
Files in kontirol/apidoc
Package apidoc
Short Description Generate OpenAPI 3.0 (Swagger) documentation from PHP controller annotations, with optional framework route introspection.
License MIT
FAQ
Example:
In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
- Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
- To use Composer is sometimes complicated. Especially for beginners.
- Composer needs much resources. Sometimes they are not available on a simple webspace.
- If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
- Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Informations about the package apidoc
apidoc
从 PHP 控制器的注释生成 OpenAPI 3.0（Swagger） 文档。
不需要手写 YAML，不需要继承任何基类，也不需要跑起来你的应用 —— 它只读源码。
生成的 openapi.json 可以直接导入 Swagger UI、Apifox、Postman、Knife4j。
安装
要求 PHP 7.4 以上（在 8.1 / 8.2 上验证过），唯一的运行时依赖是 symfony/yaml（只有你输出 YAML 时才会用到）。
快速开始
1. 在控制器方法上写注释
规则很简单：
- 只有带注释的方法才会被收集，没有注释的方法直接跳过。
@route里的{id}会自动变成 OpenAPI 的 path 参数，并且强制required: true。- 方法签名里的标量参数（
int $page = 1）会自动补进文档，标量以外的参数（Request $request）会跳过 —— 那是容器注入，不是接口参数。
2. 建一个 apidoc.php
也可以写成 JSON 或 YAML，文件名分别是 apidoc.json / apidoc.yaml。
3. 生成
在项目根目录下会自动找 apidoc.php、apidoc.json、apidoc.yaml 或 apidoc.yml。
注解速查
| 注解 | 说明 | 例子 |
|---|---|---|
@name |
接口标题（OpenAPI summary） |
@name 用户列表 |
@desc |
详细说明（支持多行，写到下一行即可） | @desc 分页返回用户列表 |
@route |
请求路径，{name} 表示路径变量 |
@route /api/user/{id} |
@method |
HTTP 方法，默认 GET |
@method POST |
@tag / @group |
分组，可写多个 | @tag 用户 |
@auth |
鉴权方式：bearer、apikey、none |
@auth bearer |
@param |
请求参数 | @param int page=1 页码 |
@body |
请求体（JSON 示例或 form/multipart/text） |
@body {"name":"张三"} |
@bodyParam |
表单请求体的字段 | @bodyParam file avatar 头像文件 |
@response |
响应，可写多个状态码 | @response 400 {"code":400} |
@deprecated |
标记为废弃 | @deprecated |
@ignore |
完全排除这个接口 | @ignore |
@param 的写法
- 类型后面加
!表示必填：@param int! id 订单 ID - 名字后面跟
=值表示默认值：@param int page=1 页码 - 类型映射：
int/integer→integer，float/number→number，bool→boolean，string[]→array，object/map/json→object，其它一律string - 支持联合类型，取第一个非
null的：@param int|null id 订单 ID
@response 的写法
不写状态码就是 200。状态码的中文描述（参数错误、未登录或登录已过期……）是自动补的。
JSON 里的结构会自动反推成 JSON Schema，包括嵌套对象和数组，所以 Swagger UI 里能看到完整的字段树。
@body 的写法
URL 从哪来
@route 是最可靠的方式，写什么就是什么。但如果你不想为每个方法都手写一遍，apidoc 也能按 ThinkPHP 的 pathinfo 约定推：
规则：
- 前缀优先取配置里
controllers[].prefix；没配就看命名空间 ——app\{应用}\controller→/{应用}，app\controller→ 根 - 类名原样保留（只转小写）：ThinkPHP 的
route.controller_suffix出厂值是false，所以OrderController对应/ordercontroller，而不是剥掉后缀的/order - 不做驼峰转下划线：
orderDetail()对应/orderdetail，不是/order_detail；VerifyCode对应/verifycode，不是/verify_code - 命名空间不符合这两个约定时完全不推导，不会给别的框架瞎编 URL
- 推导出来的值伴随一条
route.inferrednotice，方便区分哪些是猜的 - 写了
@route的永远以你写的为准，推导不会覆盖它
这两条规则是从哪知道的
route.source = thinkphp 时，apidoc 会向启动起来的应用问一次：
所以通常不用配。只有项目不走 ThinkPHP 的约定时（自己写了路由、用 kebab-case 之类）才需要手动指定：
不想要推导就加 --no-infer，或者在配置里写 'route' => ['infer' => false]。
零注释起步
老项目想先看看「到底有多少接口」，可以先跑一次：
--all 会把没有 apidoc 标签的方法也全部纳入：
- URL 用上面的规则推导
- HTTP 方法从方法名猜（
saveCode这种驼峰写法也认）：save_*/create_*/send_*/notify→POST，remove_*/delete_*/clear_*/cancel_*→DELETE，update_*/edit_*→PUT，其余GET summary用方法名- 参数从方法签名反射出来
- 每一条都带
endpoint.undocumentednotice，明确标明这是猜的
拿到这张接口地图之后，再往注释里补 @name / @param / @response，文档质量自然就上来了。
命令行
| 选项 | 说明 |
|---|---|
-c, --config <文件> |
指定配置文件 |
--no-reflection |
不用 PHP 反射补参数 |
--strict |
把 warning 也当成错误 |
--no-fail-on-empty |
一个接口都没扫到时也不报错 |
--all |
连没有 apidoc 标签的方法也一并文档化（见「零注释起步」） |
--no-infer |
不自动推导缺失的 @route |
-v, --verbose |
打印扫描的目录和 notice 级诊断 |
-q, --quiet |
只打印错误 |
-h, --help |
帮助 |
退出码（方便挂 CI）：
| 码 | 含义 |
|---|---|
0 |
成功 |
1 |
跑不起来（配置错、文件不可写……） |
2 |
文档生成了，但有 error 级问题（比如两个接口占用同一个 方法 + 路径） |
validate 会额外检查重复路由、缺失路由、缺失标题，正好适合放进 pre-commit 或 CI：
所有诊断码（共 15 个）的含义和修法见 docs/diagnostics.md。
配置项
相对路径一律相对于配置文件所在目录解析。
它是怎么工作的
整体的设计原则是 能少猜就少猜：
- 反射只做补全，不做反向校验 —— 因为 PHP 框架里大量参数是从
Request::get()拿的，签名里根本没有，按签名校验会满屏误报。 - 推导 URL 时，约定如果问不到框架就退回 ThinkPHP 的出厂值，绝不凭空发明。
- 路由表（如果配了）是运行时真相，如果和
@route冲突，以路由表为准，但会给你一条 warning。 - 所有能修的问题都变成诊断信息（error / warning / notice），而不是直接崩掉。
与 ThinkPHP 配合
apidoc 不依赖任何框架，ThinkPHP 项目用起来和普通 PHP 项目没区别 —— 把控制器目录配好就行。只有两个 ThinkPHP 特有的点：
1. 文件后缀。 ThinkPHP 8 默认 controller_suffix = false，控制器文件叫 Auth.php 而不是 AuthController.php，而 apidoc 默认只扫 *Controller.php：
2. URL 从哪来。 看你的项目是哪种写法：
- pathinfo 自动路由（多应用模式的默认做法，不写
route/*.php）—— ThinkPHP 的路由表里没有业务路由（只有内置的<MISS>），apidoc 按命名空间和类名推导，并按应用自身的route.controller_suffix得到正确路径。不确定推成了什么，加-v看route.inferrednotice，每条都会带上推导结果。 - 注册式路由（写了
Route::get('user/detail', 'User/detail')）—— 可以配route.source = thinkphp，apidoc 会引导你的应用、读出真实路由表，与@route交叉校验，不一致时以真实路由为准并给出 warning；@route没写但路由表里有，还会自动填上。
细节和排查工具见 docs/thinkphp.md。
开发
想快速看效果，仓库里带了完整的例子：
许可证
MIT
