library ddoc

wxm/ddoc

基于 laravel 框架, 读取数据库信息生成数据库字典, 通过控制器注释生成API接口文档, 注册 ddoc 路由网页形式呈现

支持 Laravel/Lumen 下控制器注释生成API文档，生成数据库字典, 注册路由呈现, _(*1)

安装

composer require wxm/ddoc --dev

配置

Laravel

1. 注册 ServiceProvider (laravel 5.5 不需要注册):, _(*2)

   Wxm\DDoc\DDocServiceProvider::class
   

2. 发布配置：, _(*3)

   php artisan vendor:publish --provider="Wxm\DDoc\DDocServiceProvider" --force
   

Lumen

1. 注册 ServiceProvider:, _(*4)

   bootstrap/app.php 下添加, _(*5)

   // 本地环境注册
   if ($app->environment('local')) {
       $app->register(Wxm\DDoc\DDocServiceProvider::class);
   }
   

2. 手动复制配置文件

使用

1. 开启服务器:, _(*6)

   php artisan serve
   

2. 访问 http://localhost:8000/ddoc, _(*7)

接口注释 生成文档

/**
 * @Resource("登录令牌", uri="/token")
 */
class AuthController extends Controller
{
    /**
     * 获取令牌
     *
     * > 通过手机号和密码获取会话`token`即登录凭证.
     * > 需要认证的请求请携带此 Authorization 头
     * >
     * > Authorization：Bearer {token}
     * > 
     *
     * @Post("/")
     * @Versions({"v1"})
     * @Response(200, body={"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9hcGkueHkudGVzdFwvc2Vzc2lvbiIsImlhdCI6MTU0NTIxNjM5OSwiZXhwIjoxNTQ1MjE5OTk5LCJuYmYiOjE1NDUyMTYzOTksImp0aSI6Im9pZjV4WTNqS2JkbEhzVmQiLCJzdWIiOjEsInBydiI6Ijg3ZTBhZjFlZjlmZDE1ODEyZmRlYzk3MTUzYTE0ZTBiMDQ3NTQ2YWEifQ.p3oAVkAxSCxTug5s6168N-ccfuCCywGDFiJ0b9zCXq8","token_type":"bearer","expires_in":3600})
     * @Parameters({
     *      @Parameter("phone", type="integer", required=true, description="手机号."),
     *      @Parameter("password", type="string", required=true, description="密码."),
     * })
     */
    public function login()
    {

    }

    /**
     * 销毁当前令牌
     *
     * * 权限要求：`登录用户`
     *
     * > 销毁成功返回 `204` 无内容 Http code
     *
     * @Delete("/")
     * @Versions({"v1"})
     * @Response(204)
     */
    public function logout()
    {

    }

    /**
     * 刷新获取新令牌
     *
     * * 权限要求：`登录用户`
     *
     * > 销毁当前令牌，获取新令牌
     *
     * @Put("/")
     * @Versions({"v1"})
     * @Response(200, body={"token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9hcGkueHkudGVzdFwvdG9rZW4iLCJpYXQiOjE1NDUyOTY3MzcsImV4cCI6MTU0NTMwMDM2NywibmJmIjoxNTQ1Mjk2NzY3LCJqdGkiOiI5Rk43TGJxZUlBc1JmZVRwIiwic3ViIjoxLCJwcnYiOiI4N2UwYWYxZWY5ZmQxNTgxMmZkZWM5NzE1M2ExNGUwYjA0NzU0NmFhIn0.qBCL-EfGYRnlxPZerpHpD9HVumjf89fVa2CBoXoFSvI","token_type":"bearer","expires_in":3600})
     */
    public function refresh()
    {

    }
}

配置 nginx 身份验证

设置账号密码, _(*8)

printf "账号:$(openssl passwd -crypt 密码)\n" >> .htpasswd

配置 nginx, _(*9)

location ~ /ddoc/ {
  auth_basic "Authorized users only";
  auth_basic_user_file .htpasswd;
  try_files $uri /index.php?$query_string;
}

参考 API Blueprint Documentation., _(*10)

参考图

, _(*11)

License

The MIT License (MIT). Please see License File for more information., _(*12)