Swagger api文檔+路由自動(dòng)注冊(cè)

dev-1.5.1-bk 版本

2024-10-25 版本更新時(shí)間

859 安裝

4 star

https://github.com/webman-tech/swagger

webman-tech/swagger

swagger openapi 在 webman 中一鍵配置啟用

安裝

composer require webman-tech/swagger

特點(diǎn)

基于 zircote/swagger-php（同時(shí)支持 Annotation 和 Attribute 模式）
支持零配置啟動(dòng)（安裝后直接訪問(wèn) /openapi 即可看到 swagger UI 的界面）
支持單應(yīng)用下多個(gè) swagger 文檔（多路由，不同 api 文檔）
支持動(dòng)態(tài)修改注解下的 swagger 文檔（解決注解下無(wú)法寫動(dòng)態(tài)配置的問(wèn)題）
支持豐富的配置（host 訪問(wèn)限制 / swagger-ui 配置 / openapi 配置）
性能優(yōu)先（服務(wù)啟動(dòng)后緩存，開發(fā)環(huán)境支持自動(dòng)更新）
支持自動(dòng)注冊(cè) webman 路由（已經(jīng)寫了 openapi 文檔，再寫一遍 webman Route 是不是多此一舉？）

使用

零配置

安裝完依賴后打開 /openapi 即可訪問(wèn) swagger 文檔

默認(rèn)掃描整個(gè) app_path()

之后在 Controller
寫對(duì)應(yīng)的注解即可，參考 zircote/swagger-php petstore.swagger.io

修改 @OA\Info 等全局的配置

第一種：通過(guò)添加注釋的方式修改

<?php

namespace app\swagger;

use OpenApi\Annotations as OA;

/**
 * @link https://swagger.io/specification/#info-object
 * @OA\OpenApi(
 *     @OA\Info(version="1.0.0", title="My App"),
 *     @OA\Server(url="/api", description="localhost"),
 * )
 */
class OpenapiSpec
{
}

第二種：通過(guò) modify 的方式修改（建議：因?yàn)檫@種方式支持更加復(fù)雜和動(dòng)態(tài)的配置）

以下 openapi_doc 支持配置在全局和應(yīng)用級(jí)別（見配置說(shuō)明）

use OpenApi\Annotations as OA;

'openapi_doc' => [
    'modify' => function(OA\OpenApi $openApi) {
        $openApi->info->title = 'My App';
        $openApi->info->version = '1.0.0';

        $openApi->servers = [
            new OA\Server(['url' => '/api', 'description' => 'localhost']),
        ];
    }
]

限制訪問(wèn)

為了保證接口文檔的安全性，不應(yīng)該讓接口暴露在公網(wǎng)環(huán)境下

默認(rèn) host_forbidden 開啟，僅內(nèi)網(wǎng)環(huán)境下可訪問(wèn)，見 HostForbiddenMiddleware

可以通過(guò)配置 app.php 中的 host_forbidden enable => false 來(lái)全局關(guān)閉

多應(yīng)用支持

默認(rèn)通過(guò)配置 app.php 中的 global_route 配置會(huì)啟用全局的掃描 app_path() 的文檔，
可以通過(guò)設(shè)置 enable => false 來(lái)關(guān)閉

在需要的地方通過(guò) (new Swagger())->registerRoute() 來(lái)手動(dòng)注冊(cè)文檔路由

如：

<?php

use Webman\Route;
use WebmanTech\Swagger\Swagger;

Route::group('/api1', function () {
    (new Swagger())->registerRoute([
        'route_prefix' => '/openapi',
        'openapi_doc' => [
            'scan_path' => app_path() . '/controller/api1',
        ],
    ]);

    Route::get('/test', [\app\controller\Test::class, 'index']);
});

Route::group('/api2', function () {
    (new Swagger())->registerRoute([
        'route_prefix' => '/my-doc',
        'openapi_doc' => [
            'scan_path' => app_path() . '/controller/api2',
        ],
    ]);

    Route::get('/test', [\app\controller\Test::class, 'index']);
});

如此配置，支持通過(guò) /api1/openapi 訪問(wèn) api1 的文檔，/api2/my-doc 訪問(wèn) api2 的文檔

配置說(shuō)明

很多配置都支持全局（多應(yīng)用共享）、應(yīng)用級(jí)別（僅當(dāng)前應(yīng)用生效）

app.php 中的配置是全局的

(new Swagger())->registerRoute($config) 中的傳參 $config 是應(yīng)用級(jí)別的

webman 路由自動(dòng)注冊(cè)

在 config 的 app.php 中修改 register_webman_route 為 true 即可自動(dòng)注冊(cè) webman 路由

路由傳參與 swagger 文檔綁定，并且支持自動(dòng)校驗(yàn)（僅支持 php>=8.1）

建立一個(gè) Schema（可同時(shí)用于 POST 和 GET）

<?php

use OpenApi\Attributes as OA;
use WebmanTech\Swagger\SchemaAnnotation\BaseSchema;

#[OA\Schema(required: ['name', 'age'])]
class TestSchema extends BaseSchema {
    #[OA\Property(description: '名稱', example: 'webman')]
    public string $name = '';
    #[OA\Property(description: '年齡', example: 5)]
    public int $age = 0;
    #[OA\Property(description: '備注', example: 'xxx')]
    public string $remark = '';

    protected function validationExtraRules() : array{
        // 此處可自定義 校驗(yàn)規(guī)則
        return [
            'age' => 'max:100',        
        ];
    }
}

控制器


use OpenApi\Attributes as OA;
use WebmanTech\Swagger\DTO\SchemaConstants;

class IndexController {
     #[OA\Post(
        path: '/xxx',
        summary: '接口說(shuō)明',
        requestBody: new OA\RequestBody(
            required: true,
            content: [
                new OA\JsonContent(
                    ref: TestSchema::class, // 簡(jiǎn)化 Body 的定義
                ),
            ],
        ),
    )]
    #[OA\Response(response: 200, description: 'null')]
    public function md(Request $request) {
        $schema = TestSchema::create($request->post(), validator()); // 自動(dòng)裝載加自動(dòng)校驗(yàn)

        // do something

        return response();
    }

    #[OA\Get(
        path: '/xxx',
        summary: '接口說(shuō)明',
        x: [
            SchemaConstants::X_SCHEMA_TO_PARAMETERS => TestSchema::class, // 該定義會(huì)自動(dòng)將 Schema 轉(zhuǎn)為 QueryParameters
        ],
    )]
    #[OA\Response(response: 200, description: 'null')]
    public function md(Request $request) {
        $schema = TestSchema::create($request->get(), validator()); // 自動(dòng)裝載加自動(dòng)校驗(yàn)

        // do something

        return response();
    }
}

注意：目前包含以下內(nèi)容