README

IQ-swagger是一个将docblocks转换为用户友好的可视化API视图（swagger）的包

入门

以下说明将帮助您在本地计算机上创建项目副本并启动开发与测试。有关如何在实时系统上部署项目的说明，请参阅部署部分。

先决条件

您需要安装哪些软件以及如何安装它们

- laravel project (5.5 >)
- PHP 7 >

安装

由于这是一个早期版本，您需要将github添加到composer.json文件中

要将IQ-swagger添加到您的Laravel项目中，您需要将以下行添加到composer.json文件中

    "require": {
        "Dennis1804/iq-swagger": "dev-default",
    },
"repositories": [ { "type": "vcs", "url": "https://github.com/dennis1804/iq-swagger" } ]

接下来，您需要运行composer update命令，将项目下载到vendor文件夹。然后，您需要打开您的config/app.php文件并添加包的Serviceprovider。

Dennis1804\IqSwagger\SwaggerServiceProvider::class,

除了这些，建议添加JWT-auth包。这将为您提供基于auth-token的API登录。它还将与需要token进行大多数API调用要求的swagger文档一起工作。作为替代，您可以使用bearer tokens，但这尚未经过测试。

现在代码已经准备好了，您可以使用以下命令将JavaScript添加到您的public文件夹中：php artisan vendor:publish

php artisan iq:swagger

该包还附带了一个Artisan命令，每次您编辑了docblock时都需要执行。该命令将读取所有的docblocks并将它们格式化为swagger.yaml/json文件。您只需执行以下命令：php artisan iq:swagger 这将读取所有包含api的路由。

docblock

docblock几乎与您通常写的docblock相同（在sublime中输入：doc_f），除了有一个变化。由于swagger需要知道输入是否必需，因此您需要在输入中添加一个布尔值，如下所示

    /**
     * function authenticate
     *
     * @consumes multipart/form-data
     *
     * @param string email The email-address of the user true
     * @param string password the users password true
     * 
     * @return json
     * @author Dennis
     **/

我们将从上到下解释docblock中的每一行及其功能。

###function function authenticate 仅声明函数名为 "authenticate"。

消费

* @consumes multipart/form-data

消费是一个自定义添加的功能，可以识别应用程序需要的数据类型。以下类型可供选择。

"multipart/form-data",                  (POST)
"application/x-www-form-urlencoded"     (GET)

params

在@param属性中，您可以识别从@consumes期望的内容，例如示例中的方法为post；它需要一个字符串：email和一个字符串：password。

 * @param string email The email-address of the user true
 * @param string password the users password true

参数有几个属性；

Identifier                      @param
Type                            string
Name                            email
Description                     The email-address of the user
Required                        true

类型

有多种类型可供选择；最重要的类型


    string
    number
    integer
    boolean
    array
    object
    file

名称

这只是您可以赋予输入字段的名称。

必需的

布尔值，true或false。表示元素是否必需。

描述

元素的简要描述。

url

这是一个定制的@param，它使用与之前相同的属性，唯一的不同之处在于它识别URL参数。如果我们有一个如下所示的路由

 Route::post('data/{checklistId}',  'Api\V1\Checklist\ChecklistController@pushData')    ->name('api.v1.checklist.pushData');

您可以添加一个URL参数

@url number checklistId required the checklist id

现在可以在swagger页面上填充URL参数。

标识返回的内容类型。可以是以下之一；

"application/xml"
"application/json"

作者

您的姓名。

访问文档

您只需在执行了php artisan iq:swagger命令后访问：http://your-domain.dev/api。

denis1804 / iq-swagger

维护者

详细信息