README

Laravel 5 API文档生成器，基于 Swagger

apidoc 只需在控制器方法中添加几行代码。

安装

使用以下命令通过composer安装此包

composer require despark/apidoc

之后，将其添加到config/app.php中的providers数组中

Despark\Apidoc\ApiDocServiceProvider::class,

然后调用

php artisan vendor:publish

现在，您就可以使用生成器了。

用法

如果您完成了上述所有步骤，那么/yourapp/config/apidoc.php文件应该为您生成。

<?php
return [
    'apiVersion'     => '1.0.0',
    'apiTitle'       => 'My api',
    'apiDescription' => 'My api',
    'apiBasePath'    => '/api/v1',
    'authorization' => 'jwt'
];

所有这些参数都在swagger API文档页面上显示，因此您可以更改它们以适应您的设置。

授权

默认情况下，swagger配置为使用JWT通过授权头：Bearer进行认证。如果您想通过查询使用标准认证，只需将授权选项更改为null。

目前，这些是唯一可用的授权选项。

控制器和方法

在apidoc文档方式中记录的每个方法，并且存在于laravel的routs.php中，都将被解析并在API文档中显示。方法文档示例

    /**
     * @apiDesc A description of the method
     * @apiParam string $parameterName required in_path | Description of the parameterName  
     * @apiParam array $parameterName2 | Description2 of the parameterName
     *
     * @apiErr 422 | Validation errors
     * @apiErr 403 | Unauthorized access
     * @apiResp 200 | Whatever message is send from backend on sucess
     */
    public function index($id, DesignRequest $request){}

注意：每个"@api"元素和描述都应该在同一行上。

@apiDesc - 方法的描述
@apiParam - 参数没有限制。参数可以是必需的或非必需的。如果输入required单词，则参数被标记为必需。请参阅上面的示例。

参数类型
- string
- file - 可上传的文件
- array
- bool或boolean（两者均可使用，且相等）
- integer
- password
- double
@apiErr XXX - 可以有多个错误消息，这些错误消息将返回在响应中。XXX是HTTP状态码。
@apiResp XXX - API调用的响应数据。XXX是HTTP状态码。
URL参数（如示例中的id），将自动获取并声明为整数

您可以选择如何发送参数，这里有3个选项

formData - 这是默认选项，不需要在注释中提及
in_path - 参数值实际上是操作URL的一部分。例如，在/items/{itemId}中，路径参数是itemId。
in_query - 添加到URL中的参数。例如，在/items?id=123中，查询参数是id。
更多信息请参考 Swagger规范页面

注意：“|”符号之后的所有内容都假定是描述性文本。因此，请在一行上只使用一个“|”符号。

命令

设置完成后，控制器在route.php文件中声明，并在控制器中有注释，我们可以调用命令。

php artisan apidoc:generate

就是这样。现在您可以通过APP_URL/docs#/访问您的新文档。

注意 APP_URL用于swagger集成。如果未在您的.env文件中设置，命令将返回一条消息，要求您设置APP_URL。
注意 APP_URL示例： http://example.info/

despark / apidoc

维护者

详细信息

README

安装

用法

授权

控制器和方法

命令