maqe/maqe-api-docs

一个帮助您构建laravel API文档的包

维护者

详细信息

bitbucket.org/maqe/maqe-api-docs

主页

源代码

安装: 2

依赖者: 0

建议者: 0

安全: 0

类型：package

dev-master 2021-05-24 06:23 UTC

Requires (Dev)

MIT c3ceaadf5e059e307417b8bde6e3b1b9da0fd116

  • Maqe Teams <hello.woop@maqe.com>

packagelaravel

This package is not auto-updated.

Last update: 2024-09-17 15:39:11 UTC

README

目录

MAQE API DOCS 📄📄

MAQE API DOCS 是一个包，可以使您为laravel项目创建的API文档工作变得更加容易

关于API文档 🤷

在使用MAQE API DOCS之前，请先了解一些基本概念~

Maqe Api Docs 将生成特定的文档，这意味着必须遵循预定义的模式，分为5个主要部分

  1. 我们需要自己定义菜单，可以在名为 config/maqe-api-docs.php 的配置文件中进行设置
  2. 我们需要创建自己的blade文件，并将其与配置文件关联（有关详细信息，请参阅一步一步部分）
  3. 我们需要在blade文件中指定请求参数，可以使用Request类来指定 Attributes，并可以添加额外的 queries 和 Attributes（有关详细信息，请参阅一步一步部分）
  4. 对于每个route的响应部分，我们需要编写测试来生成响应。好处是这确保我们必须编写测试来返回值，可以查看 tests/Feature/ExampleTest.php 文件中的示例或一步一步部分
  5. 在此处，我们需要手动打印命令以运行或我们可以调用脚本以在部署时运行它来更新版本和更新日期

一步一步[安装] 👩‍🏫

使用方法

  1. 在您正在工作的项目中安装此包，有关详细信息，请参阅此处
  2. 运行安装命令以自动发布和安装配置
php artisan maqe-api-docs:install

# หลังจากที่เรารันคำสั่ง ระบบจะทำการสร้างไฟล์ต่าง และอัพเดตไฟล์ที่จำเป็นให้เราตาม path ด้านล่างนี้

# Script file...
./.scripts/gitlog.sh

# config file...
./config/maqe-api-docs.php

# view files...
./resources/views/maqe-api-docs/components/access_token.blade.php
./resources/views/maqe-api-docs/components/attribute.blade.php
./resources/views/maqe-api-docs/components/method.blade.php
./resources/views/maqe-api-docs/components/role.blade.php
./resources/views/maqe-api-docs/pages/exampleFolder
./resources/views/maqe-api-docs/pages/exampleFolder/examples.blade.php
./resources/views/maqe-api-docs/pages/examples.blade.php
./resources/views/maqe-api-docs/endpoint.blade.php
./resources/views/maqe-api-docs/index.blade.php
./resources/views/maqe-api-docs/layout.blade.php
./resources/views/maqe-api-docs/nav.blade.php

# tests file...
./tests/Feature/MaqeApiDocsExampleTest.php

# update route file...
./routes/web.php
  1. 然后运行命令以创建 .gitlog 文件，以指定我们的API版本更新
sh ./.scripts/gitlog.sh
  1. 运行测试文件 MaqeApiDocsExampleTest.php，我们可以使用它作为生成response json文件的示例
php artisan test --filter MaqeApiDocsExampleTest
  1. 通过访问route docs 进行测试，例如，如果您使用 php artisan serve 运行项目，请访问 http://127.0.0.1:8000/docs

一步一步[开发] 👩‍🏫

创建新的API和创建我们创建的API的文档

  • 创建从示例创建的资源route
// routes/web.php

<?php

use Illuminate\Support\Facades\Route;

...

Route::resource('examples', \App\Http\Controllers\Document\ExampleController::class)->only([
    'index', 'show', 'store', 'update', 'destroy',
]);
  • 创建与route匹配的controller
// app/Http/Controllers/ExampleController.php

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Http\Response;
use App\Http\Controllers\Requests\DummyRequest;
use App\Http\Controllers\Requests\DummyUpdateRequest;
use App\Http\Controllers\Controller;

class ExampleController extends Controller
{
    public function index(Request $request)
    {
        // no code no bug
    }

    public function show(int $id)
    {
        // no code no bug
    }

    public function store(DummyRequest $request)
    {
        // no code no bug
    }

    public function update(DummyUpdateRequest $request, int $id)
    {
        // no code no bug
    }

    public function destroy(int $id)
    {
        // no code no bug
    }

}
  • 建议创建请求文件，以便我们可以轻松地将它们用于API文档
// app/Http/Controllers/Document/Requests/DummyRequest.php

<?php

namespace App\Http\Controllers\Requests;

use Illuminate\Foundation\Http\FormRequest;

class DummyRequest extends FormRequest
{
    public function rules()
    {
        return [
            'name' => ['required', 'string'],
        ];
    }
}
  • 然后创建测试文件，并在其中使用maqe api docs类来创建我们将用于API文档的响应文件
    • 声明静态变量，然后在 setUpBeforeClass 中初始化实例
    • 通过调用url并生成用于创建API文档的response json文件来测试
    • 创建将在最后发生，因此请在 tearDown 函数中运行 write response 命令
// tests/Feature/MaqeApiDocsExampleTest.php

<?php

namespace Tests\Feature;

use Illuminate\Http\Response;

use Maqe\MaqeApiDocs\Docs;
use Tests\TestCase;

class MaqeApiDocsExampleTest extends TestCase
{
    private static Docs $maqeApiDocs;

    public static function setUpBeforeClass(): void
    {
        parent::setUpBeforeClass();
        self::$maqeApiDocs = new Docs;
    }

    public function test_document_example_index_()
    {
        $response = $this->get('/examples');

        $response->assertStatus(Response::HTTP_OK);

        self::$maqeApiDocs->saveResponse(
            'examples.index',
            $response,
            '200 OK'
        );
    }

    public function test_document_example_index_with_query_string()
    {
        $response = $this->get('/examples?q=2');

        $response->assertStatus(Response::HTTP_OK);

        self::$maqeApiDocs->saveResponse(
            'examples.index',
            $response,
            '200 OK (with query string)'
        );
    }

    public function test_document_example_show()
    {
        $response = $this->get('/examples/2');

        $response->assertStatus(Response::HTTP_OK);

        self::$maqeApiDocs->saveResponse(
            'examples.show',
            $response,
            '200 OK'
        );
    }

    public function test_document_example_show_not_found()
    {
        $response = $this->get('/examples/9999999999');

        $response->assertStatus(Response::HTTP_NOT_FOUND);

        self::$maqeApiDocs->saveResponse(
            'examples.show',
            $response,
            '404 NOT FOUND'
        );
    }

    public function test_document_example_created()
    {
        $response = $this->post('/examples', [
            'name' => 'name1',
        ]);

        $response->assertStatus(Response::HTTP_CREATED);

        self::$maqeApiDocs->saveResponse(
            'examples.store',
            $response,
            '201 CREATED'
        );
    }

    public function test_document_example_updated()
    {
        $response = $this->put('/examples/1', [
            'name' => 'nameUpdate',
        ]);

        $response->assertStatus(Response::HTTP_OK);

        self::$maqeApiDocs->saveResponse(
            'examples.update',
            $response,
            '200 OK'
        );
    }

    public function test_document_example_deleted()
    {
        $response = $this->delete('/examples/1');

        $response->assertStatus(Response::HTTP_OK);

        self::$maqeApiDocs->saveResponse(
            'examples.destroy',
            $response,
            '200 OK'
        );
    }

    public function tearDown(): void
    {
        self::$maqeApiDocs->writeResponse();
        parent::tearDown();
    }
}
  • 通过在 pages 文件夹中创建文件来创建文档页面，例如 resources/views/maqe-api-docs/pages/<name>.blade.php 或 resources/views/maqe-api-docs/pages/<folder_name>/<name>.blade.php

<h1 class="display-4">Example API</h1>

<h3># GET</h3>
<h4>Index</h4>
@include('maqe-api-docs.endpoint', [
    'name' => 'examples.index',
    'queries' => [
        'q' => [
            'rule' => 'string', 'description: query string for search by keyword',
        ],
    ],

])
<hr class="mb-4" />

<h3># GET</h3>
<h4>Show</h4>
@include('maqe-api-docs.endpoint', ['name' => 'examples.show'])
<hr class="mb-4" />

<h3># POST</h3>
@include('maqe-api-docs.endpoint', [
    'name' => 'examples.store',
    'request' => App\Http\Controllers\Requests\DummyRequest::class,
])
<hr class="mb-4" />

<hr class="mb-4" />
<h3># PUT</h3>
@include('maqe-api-docs.endpoint', [
    'name' => 'examples.update',
    'request' => App\Http\Controllers\Requests\DummyUpdateRequest::class,
])
<hr class="mb-4" />

<h3># DELETE</h3>
@include('maqe-api-docs.endpoint', ['name' => 'examples.destroy'])

使用 @include('documents.endpoint', []) 来渲染数据，根据我们设置的route显示信息

其中 'name' => 'controller.name'，其中 controller.name 是我们route的名称。如果不确定我们创建的route的名称，可以运行 php artisan route:list 命令来检查

此外，我们还可以创建请求类，以便在需要时可以轻松地使用。例如，如果需要添加参数，可以使用 'request' => Request::class。从示例中，Request::class 是 App\Http\Controllers\Requests\DummyRequest::class 和 App\Http\Controllers\Requests\DummyUpdateRequest::class

此外，我们还可以为API文档添加额外的查询

@include('maqe-api-docs.endpoint', [
    'name' => 'examples.index',
    'queries' => [
        'q' => [
            'rule' => 'string', 'description: query string for search by keyword',
        ],
    ],

])

> 在某些情况下，如果我们需要使用与route不同的名称来使用自定义响应，我们可以通过以下方式来定义响应：

 @include('documents.endpoint', ['name' => 'passport.token', 'response' => 'passport.token.guest'])
  • 管理配置
// config/maqe-api-docs.php

<?php

return [

    // ใช้สำหรับแสดง title และ subtitle ใน api docs
    'info' => [
        'title' => 'MAQE API Document',
        'description' => 'MAQE API Documentation description',
    ],
    // 
    'pages' => [
        'Example' => [
            'exampleFolder-examples' => 'Example API',
        ],
        'Example No Folder' => [
            'examples' => 'Example API',
        ],
    ],
];

例如，在 pages 下的配置将显示在侧边栏中，如上面的示例所示，它显示并链接到指定的文件

  • 示例
    • 示例API（单击将带您到 ./resources/views/maqe-api-docs/pages/exampleFolder/examples.blade.php 文件）
  • 无文件夹示例
    • 示例API（单击将带您到 ./resources/views/maqe-api-docs/pages/examples.blade.php 文件）

>祝您编码愉快！