• 需求
• 使用方法
  • 错误: apidoc 未找到
  • 共享响应，以更快地更新和更少的过时响应
• 编辑模板中默认生成的值:
• 更改文档URL的
• 编辑文档头
• API文档头文件示例

每个伟大的API都需要一个伟大的文档。
使用 php artisan Apiato:docs 命令，可以非常轻松地编写和生成文档。

需求

安装 ApiDocJs 工具，建议先阅读Routes

使用

1 - 像这样在端点上编写一个PHP 注释:
For more info about the parameters check out ApiDocJs documentation

<?php

/**
 * @api的分组           授权
 * @api的名字            UserLogin
 * @api                {post} /users/login  用户登录
 * @api描述     描述在这
 * @api的版本         1.0.0
 * @api的许可      none
 *
 * @api的头          Accept application/json
 *
 * @api的参数           {String}     email
 * @api的参数           {String}     password
 *
 * @api成功的案例  {json}       Success-Response:
 *   HTTP/1.1 200 OK
 *   {
 *     "data": {
 *       "id": "owpzanmh",
 *       "name": "Super Admin",
 *       "email": "admin@admin.com"
 *       ...
 *   }
 *
 * @api的错误的案例  {json}       Error-Response:
 *   {
 *      "message":"401 Credentials Incorrect.",
 *      "status_code":401
 *   }
 *
 * @api的错误案例  {json}       Error-Response:
 *   {
 *      "message":"Invalid Input.",
 *      "errors":{
 *         "email":[
 *            "The email field is required."
 *         ]
 *      },
 *      "status_code":422
 *   }
 */

$router->post('users/login', [
    'uses' => 'Controller@userLogin',
]);

足矣: 所有的路由注释必须写在路由文件中，否则它们将不会被加载.

2 - 在更目录运行文档生成命令:

php artisan apiato:docs

3 - 在你的客户端访问以下这个链接:

• 公共的api文档： http://apiato.develop/api/documentation/

• 私有的api文文档 http://apiato.develop/api/private/documentation/.

  注意: 每次更改路由文件的注释时，都需要运行此命令。

  错误: ApiDoc 未找到

  如果你得到一个错误(' apidoc未找到')。

1、打开 container 的配置文件 Containers/Documentation/Configs/apidoc.php。
2、编辑 executable 的目录 $(npm bin)/apidoc 或您访问计算机上的 apidoc工具的方式。

<?php
    /*
    |--------------------------------------------------------------------------
    | 可执行的
    |--------------------------------------------------------------------------
    |
    | 指定如何在计算机上运行或访问`apidoc`工具。
    |
    */

    'executable' => 'apidoc',

共享响应，以更快更新和更少的超时响应:

为了防止路由之间的响应重复，让我们为每个对象创建一个共享响应。
例如: _user.v1.public.php 将包含所有的用户响应(单个，多个...)。

<?php

/**
 * 
 * @api定义了 UserSuccessSingleResponse
 * @api 成功响应的案例  {json} Success-Response:
 * 
HTTP/1.1 200 OK
{
   "data":{
      "object":"User",
      "id":eqwja3vw94kzmxr0,
   },
   "meta":{
      "include":[],
      "custom":[]
   }
}
 */

使用来自任何路由的共享用户响应:

* @apiUse UserSuccessSingleResponse

为了避免不得不为同一个对象生成和升级单个的或者多个的响应（仅推荐用于私有API），你可以使用共享的多个响应 * @apiUse GeneralSuccessMultipleResponse ，你可以在 app/Containers/Documentation/UI/API/Routes/* 中找到他并且修改他。

编辑模板中默认生成的值:

Apiato 默认会生成 两个 Api文档的。每个都有自己的 apidoc.json 文件。两者都可以从 Containers/Documentation/ApiDocJs/ 中的文档容器中进行修改。

apidoc.json 案例文件:

{
  "name": "Apiato",
  "description": "Apiato (Private API) Documentation",
  "title": "Welcome to Apiato",
  "version": "1.0.0",
  "url" : "http://api.apiato.develop",
  "template": {
    "withCompare": true,
    "withGenerator": true
  },
  "header": {
    "title": "API Overview",
    "filename": "app/Containers/Documentation/ApiDocJs/private/header.md"
  },
  "footer": {
    "title": "Footer",
    "filename": "app/Containers/Documentation/ApiDocJs/private/header.md"
  },
  "order": [

  ]
}

更改文档的URL

编辑文档容器的配置文件 Containers/Documentation/Configs/apidoc.php

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | 可执行
    |--------------------------------------------------------------------------
    |
    | 指定如何在计算机上运行或访问`apidoc`工具。
    |
    */

    'executable' => 'apidoc',

    /*
    |--------------------------------------------------------------------------
    | API类型
    |--------------------------------------------------------------------------
    |
    | 通过在类型名称下对多个文档进行分组，“类型”有助于生成多个文档。您可以添加或删除任何类型。默认情况下，设置“public”和“private”类型。
    |
    | url: 访问生成的API文档的url。
    |
    | routes: 生成此文档时要读取的路由文件。
    |        每个路由文件将具有以下名称格式:
    |         `{endpoint-name}.v{version-number}.{documentation-type}.php`.
    |
    */

    'types' => [

        'public' => [
            'url' => 'api/documentation',
            'routes' => [
                'public',
            ],
        ],

        'private' => [
            'url' => 'api/private/documentation',
            'routes' => [
                'private',
                'public',
            ],
        ],
    ],

    /*
    |--------------------------------------------------------------------------
    | HTML文件
    |--------------------------------------------------------------------------
    |
    | 指定将生成的HTML文件放置在何处。
    |
    */

    'html_files' => 'public/'

    // ...
];

编辑文档的头

头通常是API的概述。它包含有关用户身份验证、发出请求、响应、潜在错误、速率限制、分页、查询参数和任何您想要的信息。

所有这些信息都写在app/Containers/Documentation/ApiDocJs/shared/header.template中，并且相同的文件被用作私有和公共文档的头文件。
要编辑内容，只需在任何makedown编辑器中打开makedown文件并编辑它。

您将注意到一些变量，如and。当从应用程序配置文件中使用真实值运行“apidoc:generate”时，这些值将被替换。

Feel free to extend them to include more info about your API from the
可以随意继承它们 app/Containers/Documentation/Actions/ProcessMarkdownTemplatesAction.php 类，以包含更多关于API的信息。

API文档头文件示例

提醒，这里本有一张案例的截屏，但是联系了官方的github，暂时无法获取到图片