PHP code example of kontirol / apidoc

    
        
<?php
require_once('vendor/autoload.php');

/* Start to develop here. Best regards https://php-download.com/ */

    

kontirol / apidoc example snippets

namespace App\Api\Controller;

class UserController
{
    /**
     * 分页返回用户列表。
     *
     * @name 用户列表
     * @route /api/user/list
     * @method GET
     * @tag 用户
     * @auth bearer
     * @param int page=1 页码
     * @param int size=10 每页数量
     * @param string keyword 昵称关键字
     * @response 200 {"code":200,"message":"ok","data":{"total":42,"list":[{"id":1,"nickname":"张三"}]}}
     */
    public function index(): array
    {
        return [];
    }

    /**
     * @name 用户详情
     * @route /api/user/{id}
     * @method GET
     * @tag 用户
     * @auth bearer
     * @param int! id 用户 ID
     * @response 200 {"code":200,"message":"ok","data":{"id":1,"nickname":"张三"}}
     * @response 404 {"code":404,"message":"用户不存在"}
     */
    public function detail(int $id): array
    {
        return [];
    }
}

return [
    'controllers' => [
        ['path' => __DIR__ . '/app/Api/Controller', 'namespace' => 'App\\Api\\Controller'],
    ],
    'output' => [
        'json' => __DIR__ . '/public/openapi.json',
    ],
    'info' => [
        'title' => '我的项目接口文档',
        'version' => '1.0.0',
    ],
    'servers' => ['http://localhost:8000'],
];

@response 200 {"code":200,"data":{"id":1}}
@response 400 {"code":400,"message":"参数错误"}

@body {"name":"张三","age":18}          // JSON 请求体，自动推断 schema
@body form                              // 表单
@body form name=张三 age=18             // 表单 + 示例字段
@body multipart                         // 文件上传，字段用 @bodyParam 声明

$app->config->get('route.controller_suffix');   // false，出厂值
$app->config->get('app.url_convert');           // true，URL 转小写

'url' => [
    'controller_suffix' => true,    // auto（默认）| true | false
    'case' => 'kebab',              // auto（默认）| lower | snake | kebab | keep
],

return [
    // 要扫描的控制器目录，可以是字符串、字符串数组，或带命名空间前缀的数组
    'controllers' => [
        ['path' => 'app/Api/Controller', 'namespace' => 'App\\Api\\Controller'],
    ],

    // 输出文件，键是格式（json / yaml），值可以是相对路径
    'output' => [
        'json' => 'public/openapi.json',
        'yaml' => 'public/openapi.yaml',
    ],

    // OpenAPI 的 info 段
    'info' => [
        'title' => '接口文档',
        'version' => '1.0.0',
        'description' => '',
    ],

    'servers' => ['http://localhost:8000'],

    // 全局鉴权
    'security' => [
        'schemes' => [
            'bearerAuth' => ['type' => 'http', 'scheme' => 'bearer', 'bearerFormat' => 'JWT'],
        ],
        'default' => ['bearerAuth' => []],
    ],

    // 标签说明
    'tags' => ['用户' => '用户中心相关接口'],

    // 扫描细节
    'scan' => [
        'suffix' => 'Controller.php',
        'exclude' => ['vendor', 'node_modules', 'tests', 'runtime'],
    ],

    'strict' => false,                 // 等同 --strict
    'fail_on_empty' => true,           // 一个接口都没扫到就失败
    'reflection' => true,              // 用反射补参数
    '

'scan' => ['suffix' => '.php'],

@param <类型> <名字>[=<默认值>] <说明>

app/api/controller/OrderController.php::myorders()
    namespace app\api\controller   ->  /api
    类名 OrderController            ->  ordercontroller
    方法 myorders                   ->  myorders
                    ↓
            /api/ordercontroller/myorders

bash
php bin/apidoc generate -c examples/apidoc.php
# 产物在 build/openapi.json 和 build/openapi.yaml