README

自动从现有的Laravel路由和类/方法注释中生成API文档

php artisan y2apidoc:generate

一些截图

先决条件

PHP 7
Laravel 5.6

安装

$ composer require delejt/y2apidoc

发布配置和模板文件

php artisan vendor:publish --provider="Delejt\Y2apidoc\ServiceProvider" --tag="config"

php artisan vendor:publish --provider="Delejt\Y2apidoc\ServiceProvider" --tag="template"

配置

在您生成文档之前，您需要配置 config/y2apidoc.php 中的几个设置

配置API路由前缀

 'route' => [
     'prefix' => 'api',
 ],

更改文档输出路径

'documentation' => [
    'output' => 'public/api-documentation',
 ...

您可以为文档更改模板（默认为bootstrap 3.3简单模板）

'source' => 'resources/views/vendor/y2apidoc/default',

自定义标签的特殊模板路径，文件名必须为 [tag_name]tag.blade.php，例如：tabletag.blade.php

'tags_template_path' => 'resources/views/vendor/y2apidoc/default/_partials/tags',

指定自定义语言模板（PHP/Shell包含在内）

'languages' => 'resources/views/vendor/y2apidoc/default/_partials/langs',

指定解析器可用的标签（或添加自己的），您可以将自定义渲染器类放在这里

'tags' => [
    "@table" => [
        'class' => '\\Delejt\\Y2apidoc\\Tags\\TableTag',
    ],
     "@notice" => [
         'class' => '\\Delejt\\Y2apidoc\\Tags\\NoticeTag',
     ],
     "@warning" => [
         'class' => '\\Delejt\\Y2apidoc\\Tags\\WarningTag',
     ],
     //"@api" => [],
     "@author" => [],

...

指定添加到所有请求的默认标题

 'request' => [
     'headers' => [
         'Accept' => 'application/json',
         'Content-Type' => 'application/x-www-form-urlencoded',
         'Authorization' => 'Bearer: {token}',
     ],

指定绑定 - 变量将在文档生成过程中自动替换

'bindings' => [
     '{token}' => 'qwerty',
     '{page}' => '1',
     '{item_per_page}' => '30',
     '{page?}' => '1',
     ...

指定用于标记方法为PUT/POST/PATCH/DELETE/GET的Bootstrap类

 'classes' => [
     'get' => 'success',
     'post' => 'primary',
     'put' => 'warning',
     'delete' => 'danger',
 ],

配置自动添加到每个响应的标题

 'response' => [
     'headers' => [
         'Content-Type' => 'application/json',
         'Accept' => 'application/json',
     ],
 ],

文档

Y2apidoc使用HTTP控制器文档注释来创建目录和显示API方法的描述。包会自动从控制器名称创建组。该控制器处理的所有路由都将放在侧边菜单中的这个组下面侧边菜单

@response {
    "success": true,
    "data": {
      "id": 55597,
      "product_id": 59863,
      "warehouse_id": 1,
      "quantity": 1333,
      "delivery_time": 48,
      "created_at": "2018-09-25 10:43:25",
      "updated_at": "2018-12-07 12:29:09"
    },
    "message": "Record updated successfully."
  }

@responsefile 标签用于显示当前方法的响应 - 请参阅响应文件部分
```
@responsefile product.index.json
```

自定义标签...

您可以通过将其名称添加到配置文件中来定义自定义标签，示例

'tags' => [
    "@mikimouse",
...

您可以通过放置类路径来指定此标签的自定义渲染器

 "@mikimouse" => [
     'class' => '\\Some\\Custom\\Namespace\\MikiMouseTag',
 ],

接下来，在指定路径中创建具有 'parse' 方法的类

<?php namespace Some\Custom\Namespace;

class MikiMouseTag
{
    public function parse($body)
    {
        return 'Hello I am MikiMouse';
    }

}

您的自定义标签现在可在您的文档注释中使用。如果您想创建具有自定义模板的标签，

<?php namespace Some\Custom\Namespace;

class MikiMouseTag
{
    public function parse($body)
    {
        return $this->render($body);
    }

    protected function render($body)
    {
        $template_name = 'mikimouse';

        try {
            return view($template_name)->with('text', $body);
        }
        catch (\Exception $e) {
            return $body;
        }
    }
    
}

接下来，将模板放入您的 tags_template_path

mikimouse.blade.php

添加一些HTML

<div class="alert alert-info" role="alert">I'am Miki Mouse</div>

这就完成了。现在您准备好生成API文档了 :)

自定义编程语言选项卡

要定义自定义语言选项卡，只需在配置文件中声明的路径中创建blade模板

 /*
  * Path for templates with languages
  */
  'languages' => 'resources/views/vendor/y2apidoc/default/_partials/langs',

此文件名应该是当前语言的名称

javascript.blade.php

此模板中可用的变量列表

url - 带参数的解析url，例如：https://domain.xxx/api/product_stocks/1/30
endpoint - 端点路由，例如：https://domain.xxx/api/product_stocks/{page}/{item_per_page}
request_type - GET/POST/PUT等。
default_headers - 配置文件中定义的默认标题数组
body_params - 身体参数数组

响应文件

您可以通过在文档注释中添加 @responsefile 来为当前方法指定响应文件

@responsefile product.stocks.store.json

在文档生成过程中，包将尝试在 storage/api 目录中找到 product.stocks.index.json 文件响应文件示例

{
  "success": true,
  "data": {
    "product_id": 16,
    "warehouse_id": 2,
    "quantity": 10,
    "delivery_time": 48,
    "updated_at": "2018-12-07 12:24:11",
    "created_at": "2018-12-07 12:24:11",
    "id": 204022
  },
  "message": "Record created successfully."
}

构建于

ReflectionDocBlock - phpDocumentor 的 ReflectionDocBlock 组件
highlight.php - 用 PHP 编写的服务器端代码高亮工具
Bootstrap 3.3 - Bootstrap 是最受欢迎的 HTML、CSS 和 JS 框架

作者

克日什托夫·切尔斯科夫斯基 - 初始工作

许可证

本项目采用 MIT 许可证 - 详细信息请参阅 LICENSE.md 文件

待办事项

测试
更好的文档
更多示例
演示

delejt / y2apidoc

维护者

详细信息