mirror of
https://gitee.com/hyperf/hyperf.git
synced 2024-12-05 21:28:15 +08:00
4.3 KiB
4.3 KiB
Hyperf Swagger
hyperf/swagger 元件基於 zircote/swagger-php 進行封裝
如需完整支援的註釋列表,請檢視OpenApi\Annotations 名稱空間或文件網站
安裝
composer require hyperf/swagger
配置
php bin/hyperf.php vendor:publish hyperf/swagger
引數名 | 作用 |
---|---|
enable | 是否啟用 Swagger 文件生成器 |
port | Swagger 文件生成器的埠號 |
json_dir | Swagger 文件生成器生成的 JSON 檔案儲存目錄 |
html | Swagger 文件生成器生成的 HTML 檔案儲存路徑 |
url | Swagger 文件的 URL 路徑 |
auto_generate | 是否自動生成 Swagger 文件 |
scan.paths | 需要掃描的 API 介面檔案所在的路徑,一個數組 |
生成文件
如果配置了 auto_generate
,在框架初始化的事件中便會自動生成文件,無需再次呼叫
php bin/hyperf.php gen:swagger
使用
以下出現的 OA 名稱空間都為
use Hyperf\Swagger\Annotation as OA
框架可以啟動多個 Server,每個 Server 的路由可以根據 OA\Hyperferver
註解來區分,並生成不同的 swagger 檔案(以該配置作為檔名)
可以配置在控制器類或者方法上
#[OA\HyperfServer('http')]
#[OA\Post(path: '/test', summary: 'POST 表單示例', tags: ['Api/Test'])]
#[OA\RequestBody(
description: '請求引數',
content: [
new OA\MediaType(
mediaType: 'application/x-www-form-urlencoded',
schema: new OA\Schema(
required: ['username', 'age'],
properties: [
new OA\Property(property: 'username', description: '使用者名稱欄位描述', type: 'string'),
new OA\Property(property: 'age', description: '年齡欄位描述', type: 'string'),
new OA\Property(property: 'city', description: '城市欄位描述', type: 'string'),
]
),
),
],
)]
#[OA\Response(response: 200, description: '返回值的描述')]
public function test()
{
}
#[OA\Get(path: '/test', summary: 'GET 示例', tags: ['Api/Test'])]
#[OA\Parameter(name: 'username', description: '使用者名稱欄位描述', in : 'query', required: true, schema: new OA\Schema(type: 'string'))]
#[OA\Parameter(name: 'age', description: '年齡欄位描述', in : 'query', required: true, schema: new OA\Schema(type: 'string'))]
#[OA\Parameter(name: 'city', description: '城市欄位描述', in : 'query', required: false, schema: new OA\Schema(type: 'string'))]
#[OA\Response(
response: 200,
description: '返回值的描述',
content: new OA\JsonContent(
example: '{"code":200,"data":[]}'
),
)]
public function list(ConversationRequest $request): array
{
}
配合驗證器
SA\Property
註解中,我們可以增加 rules
引數,然後配合 SwaggerRequest
即可在中介軟體中,驗證引數是否合法。
<?php
namespace App\Controller;
use App\Schema\SavedSchema;
use Hyperf\Swagger\Request\SwaggerRequest;
use Hyperf\Di\Annotation\Inject;
use Hyperf\Swagger\Annotation as SA;
#[SA\HyperfServer(name: 'http')]
class CardController extends Controller
{
#[SA\Post('/user/save', summary: '儲存使用者資訊', tags: ['使用者管理'])]
#[SA\RequestBody(content: new SA\JsonContent(properties: [
new SA\Property(property: 'nickname', description: '暱稱', type: 'integer', rules: 'required|string'),
new SA\Property(property: 'gender', description: '性別', type: 'integer', rules: 'required|integer|in:0,1,2'),
]))]
#[SA\Response(response: '200', content: new SA\JsonContent(ref: '#/components/schemas/SavedSchema'))]
public function info(SwaggerRequest $request)
{
$result = $this->service->save($request->all());
return $this->response->success($result);
}
}