mirror of
https://gitee.com/hyperf/hyperf.git
synced 2024-12-04 04:37:46 +08:00
88 lines
3.2 KiB
Markdown
88 lines
3.2 KiB
Markdown
# Hyperf Swagger
|
||
|
||
hyperf/swagger 組件基於 zircote/swagger-php 進行封裝
|
||
|
||
如需完整支持的註釋列表，請查看[OpenApi\Annotations 命名空間](https://github.com/zircote/swagger-php/blob/master/src/Annotations)或[文檔網站](https://zircote.github.io/swagger-php/guide/annotations.html#arrays-and-objects)
|
||
|
||
|
||
## 安裝
|
||
|
||
```
|
||
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` ，在框架初始化的事件中便會自動生成文檔，無需再次調用
|
||
```shell
|
||
php bin/hyperf.php gen:swagger
|
||
```
|
||
|
||
## 使用
|
||
|
||
> 以下出現的 OA 命名空間都為 `use Hyperf\Swagger\Annotation as OA`
|
||
|
||
框架可以啓動多個 Server，每個 Server 的路由可以根據 `OA\Hyperferver` 註解來區分，並生成不同的 swagger 文件（以該配置作為文件名）
|
||
|
||
可以配置在控制器類或者方法上
|
||
```php
|
||
#[OA\HyperfServer('http')]
|
||
```
|
||
|
||
```php
|
||
#[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()
|
||
{
|
||
}
|
||
```
|
||
|
||
```php
|
||
#[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
|
||
{
|
||
}
|
||
```
|