README

LaraSwag 包允许您为API生成合适的文档。

安装

首先，打开命令行控制台，进入您的项目目录并执行以下命令以下载此扩展包的最新版本（仍处于测试阶段，对于稳定版本请查看这里）

composer require zquintana/lara-swag dev-master

然后，将服务提供者添加到您的应用程序配置中

ZQuintana\LaraSwag\Provider\LaraSwagProvider::class

要安装供应商资源，如配置和模板，请运行

$ php artisan vendor:publish --provider="ZQuintana\LaraSwag\Provider\LaraSwagProvider::class"

要使用Swagger UI浏览您的文档，请在 config/routing/lara_swag.php 中注册路由。在运行 vendor:publish 命令后，您可以将以下内容添加到路由配置文件中，以便更容易地完成此操作

<?php
...
Route::group(['prefix' => 'api'], function () {
    require_once('lara_swag.php'); // use routes/lara_swag.php if you're using Laravel pre 5.3
});

此扩展包做什么？

它通过 Describers 从您的Laravel应用程序生成Swagger文档。每个 Describer 都从各种来源提取信息。例如，一个从SwaggerPHP注释中提取数据，一个从您的路由中提取，等等。

如果您已配置上述路由，您可以在 http://example.org/api/docs 中浏览您的文档。

使用扩展包

您可以在配置中全局配置您的文档（查看Swagger规范以了解可用的字段）

<?php

return [
    'documentation' => [
        'info' => [
            'title'       => 'My App',
            'description' => 'This is an awesome app!',
            'version'     => '1.0.0',            
        ]    
    ],
];

要记录您的路由，您可以在控制器中使用注释

namespace App\Controllers;

use App\Models\User;
use App\Models\Reward;
use ZQuintana\LaraSwag\Annotation\Model;
use Swagger\Annotations as SWG;

class UserController
{
    /*
     * @SWG\Response(
     *     response=200,
     *     description="Returns the rewards of an user",
     *     @SWG\Schema(
     *         type="array",
     *         @Model(type=Reward::class, groups={"full"})
     *     )
     * )
     * @SWG\Parameter(
     *     name="order",
     *     in="query",
     *     type="string",
     *     description="The field used to order rewards"
     * )
     * @SWG\Tag(name="rewards")
     */
    public function fetchUserRewardsAction(User $user)
    {
        // ...
    }
}

支持什么？

此包支持 Laravel 路由要求、PHP 注释和 Swagger-Php 注释。

它通过 @Model 注释支持模型。

贡献

查看 贡献 文件。

运行测试

安装 Composer 依赖项

git clone https://github.com/zquintana/LaraSwag.git
cd LaraSwag
composer install

然后运行测试套件

./phpunit

许可

此扩展包在MIT许可下发布。