Skip to content

Commit ac20d27

Browse files
astral-dataastral-data
authored
add openapi doc (#5)
add openapi doc
1 parent 2ea1976 commit ac20d27

File tree

10 files changed

+443
-11
lines changed

10 files changed

+443
-11
lines changed

‎.openapi.php

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@
33
use Astral\Serialize\OpenApi\Storage\OpenAPI\ServersStorage;
44

55
return [
6+
7+
'doc_url' => 'http://127.0.0.1:8089',
8+
69
// API Document Title
710
'title' => 'API Docs',
811

@@ -29,7 +32,7 @@
2932
* @type ServersStorage[] $service
3033
*/
3134
'service' => [
32-
new ServersStorage('http://127.0.0.1', 'Default Environment'),
35+
new ServersStorage('http://127.0.0.1', 'Default'),
3336
],
3437

3538
/**

‎docs/zh/SUMMARY.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,8 @@
2929

3030
## 自动创建OpenApi文档
3131

32-
* [基础演示](openapi/base-openapi.md)
32+
* [基础演示](openapi/base-openapi.md)
33+
* [参数注解](openapi/annotation.md)
34+
* [重写注解](openapi/override-annotation.md)
35+
* [配置](openapi/config.md)
36+
* [启动服务](openapi/launch.md)

‎docs/zh/openapi/annotation.md

Lines changed: 241 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
# 启动服务
2+
3+
## [OpenApi] 添加属性说明 示例值
4+
5+
### 增加属性说明 示例值
6+
7+
```php
8+
use Astral\Serialize\Serialize;
9+
use Astral\Serialize\OpenApi\Annotations\OpenApi;
10+
11+
class UserAddRequest extends Serialize {
12+
13+
#[OpenApi(description: '姓名',example: '张三')]
14+
public string $name;
15+
16+
#[OpenApi(description: 'ID',example: '1')]
17+
public int $id;
18+
}
19+
```
20+
21+
### 隐藏输入属性
22+
23+
添加了 `InputIgnore` 注解类 作为`Request`类 openapi 生成文档时会自动忽略
24+
25+
```php
26+
use Astral\Serialize\Serialize;
27+
use Astral\Serialize\OpenApi\Annotations\OpenApi;
28+
use Astral\Serialize\Annotations\DataCollection\InputIgnore;
29+
30+
class UserAddRequest extends Serialize {
31+
32+
#[InputIgnore]
33+
public object $admin;
34+
35+
#[OpenApi(description: '姓名',example: '张三')]
36+
public string $name;
37+
38+
#[OpenApi(description: 'ID',example: '1')]
39+
public int $id;
40+
}
41+
```
42+
43+
### 隐藏输出属性
44+
45+
添加了 `OutputIgnore` 注解类 作为`Response`类 openapi 生成文档时会自动忽略
46+
47+
```php
48+
use Astral\Serialize\Serialize;
49+
use Astral\Serialize\OpenApi\Annotations\OpenApi;
50+
use Astral\Serialize\Annotations\DataCollection\OutputIgnore;
51+
52+
class UserAddRequest extends Serialize {
53+
54+
#[OutputIgnore]
55+
public object $admin;
56+
57+
#[OpenApi(description: '姓名')]
58+
public string $name;
59+
60+
#[OpenApi(description: 'ID')]
61+
public int $id;
62+
}
63+
```
64+
65+
tips: `OutputIgnore` 和 `InputIgnore` 的详细使用请查看 [属性忽略](../annotation/ignore-annotation.md)
66+
67+
68+
## [Headers] 添加/剔除请求头
69+
70+
* 增加 `user-token` 设置默认值 `true`
71+
* 增加 `company-id` 设置默认值 `''`
72+
* 删除 `token` 请求头
73+
74+
```php
75+
use Astral\Serialize\Serialize;
76+
77+
#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
78+
class UserController {
79+
80+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
81+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
82+
#[\Astral\Serialize\OpenApi\Annotations\Headers(headers:['user-token'=>'true','company-id'=>''], withOutHeaders: ['token'])]
83+
public function create()
84+
{
85+
return new UserDto();
86+
}
87+
88+
89+
}
90+
```
91+
92+
## [Tag] 添加栏目说明
93+
94+
每一个Controller必须添加`Tag`注解类才会正常生成openapi文档
95+
* `value` 栏目名称
96+
* `description` 栏目说明
97+
* `sort` 排序 值越大 栏目排序越靠前
98+
99+
```php
100+
#[\Astral\Serialize\OpenApi\Annotations\Tag(value:'用户模块管理', description: '说明文案', sort: 0 )]
101+
class UserController {}
102+
```
103+
104+
## [Summary] 接口方法说明
105+
106+
* `value` 方法名称
107+
* `description` 方法介绍
108+
109+
```php
110+
#[\Astral\Serialize\OpenApi\Annotations\Tag(value:'用户模块管理', description: '说明文案', sort: 0 )]
111+
class UserController {
112+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
113+
public function create()
114+
{
115+
return new UserDto();
116+
}
117+
}
118+
```
119+
120+
## [Route] 路由
121+
122+
必须存在`Route`注解类才会正常生成openapi文档 同时需要保证 路由地址唯一 如果地址重复会导致显示不一致
123+
124+
* `route` 求情路径
125+
* `method` 请求方法 默认POST
126+
127+
```php
128+
#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
129+
class UserController {
130+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
131+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
132+
public function create()
133+
{
134+
return new UserDto();
135+
}
136+
}
137+
```
138+
139+
## [RequestBody] 接口方法说明
140+
141+
### 隐式获取 RequestBody
142+
143+
当前接口入参对象 继承了 `Serialize`对象时，会自动获取该对象作为 `RequestBody`
144+
145+
```php
146+
use Astral\Serialize\Serialize;
147+
148+
class UserAddRequest extends Serialize {
149+
public string $name;
150+
public int $id;
151+
}
152+
153+
#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
154+
class UserController {
155+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
156+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
157+
public function create(UserAddRequest $request)
158+
{
159+
return new UserDto();
160+
}
161+
}
162+
```
163+
164+
### RequestBody Group分组显示文档
165+
166+
`RequestBody` 指定了 group openapi 生成文档会显示该分组下的属性
167+
168+
```php
169+
use Astral\Serialize\Serialize;
170+
use Astral\Serialize\Attributes\Groups;
171+
172+
class UserAddRequest extends Serialize {
173+
[Groups('edit','add')]
174+
public string $name;
175+
176+
[Groups('edit')]
177+
public int $id;
178+
}
179+
180+
#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
181+
class UserController {
182+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
183+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
184+
#[\Astral\Serialize\OpenApi\Annotations\RequestBody(groups: ['edit'])]
185+
public function edit(UserAddRequest $request) {}
186+
}
187+
```
188+
tips: Groups 详细使用请查看 [属性分组](../annotation/group-annotation.md)
189+
190+
## [Response] 接口方法说明
191+
192+
### 隐式获取 Response
193+
194+
当对象返回对象 继承了 `Serialize`对象时，会自动获取该对象作为 `Response`
195+
196+
```php
197+
use Astral\Serialize\Serialize;
198+
199+
class UserResponse extends Serialize {
200+
public string $name;
201+
public int $id;
202+
}
203+
204+
205+
#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
206+
class UserController {
207+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
208+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
209+
public function create(UserAddRequest $request): UserResponse
210+
{
211+
return new UserResponse();
212+
}
213+
}
214+
```
215+
216+
### Response Group分组显示文档
217+
218+
`Response` 指定了 group openapi 生成文档会显示该分组下的属性
219+
220+
```php
221+
use Astral\Serialize\Serialize;
222+
use Astral\Serialize\Attributes\Groups;
223+
224+
class UserResponse extends Serialize {
225+
[Groups('detail','guest')]
226+
public string $name;
227+
228+
[Groups('detail')]
229+
public int $mobile;
230+
}
231+
232+
#[\Astral\Serialize\OpenApi\Annotations\Tag('用户模块管理')]
233+
class UserController {
234+
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
235+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
236+
#[\Astral\Serialize\OpenApi\Annotations\Response(className:UserAddRequest::class, groups: ['guest'])]
237+
public function edit($request) {}
238+
}
239+
```
240+
241+
tips: Groups 详细使用请查看 [属性分组](../annotation/group-annotation.md)

‎docs/zh/openapi/base-openapi.md

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ class UserController {
3434
#[\Astral\Serialize\OpenApi\Annotations\Summary('创建用户')]
3535
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
3636
#[\Astral\Serialize\OpenApi\Annotations\RequestBody(UserAddRequest::class)]
37-
#[\Astral\Serialize\OpenApi\Annotations\Response(UserDto::class)]
37+
#[\Astral\Serialize\OpenApi\Annotations\Response(UserDto::class)]
3838
public function create()
3939
{
4040
return new UserDto();
@@ -52,11 +52,25 @@ class UserController {
5252

5353
### Docker启动
5454

55-
先进入项目根目录
55+
进入项目根目录
5656

5757
```shell
5858
docker run -v $PWD/vendor/astral/php-serialize/src/OpenApi/Frankenphp/Caddyfile:/etc/frankenphp/Caddyfile -v $PWD:/app -p 8089:80 dunglas/frankenphp
5959
```
6060
访问 `http://127.0.0.1:8089/docs` 查看文档
6161

62+
![UI-IMG](./ui.png)
63+
64+
### Docker启动
65+
66+
先进入项目根目录
67+
68+
```shell
69+
docker run -v $PWD/vendor/astral/php-serialize/src/OpenApi/Frankenphp/Caddyfile:/etc/frankenphp/Caddyfile -v $PWD:/app -p 8089:80 dunglas/frankenphp
70+
```
71+
72+
访问 `http://127.0.0.1:8089` 展示OpenApi JSON文档
73+
74+
访问 `http://127.0.0.1:8089/docs` 展示UI文档
75+
6276
![UI-IMG](./ui.png)

‎docs/zh/openapi/config.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# 配置
2+
3+
在项目根目录创建 `.openapi.php` 文件会覆盖默认配置
4+
5+
```php
6+
use Astral\Serialize\OpenApi\Storage\OpenAPI\ServersStorage;
7+
8+
return [
9+
/**
10+
* OpenApi UI 获取OpenApi Json 的地址
11+
*/
12+
'doc_url' => 'http://127.0.0.1:8089',
13+
14+
/**
15+
* API 文档的标题。
16+
*/
17+
'title' => 'API Docs',
18+
19+
/**
20+
* API 文档的描述。
21+
*/
22+
'description' => 'API Docs description.',
23+
24+
/**
25+
* 每个请求中需要添加的全局请求头。
26+
* 每个请求头应包含名称、示例和描述。
27+
*
28+
* 示例：
29+
* [
30+
* 'name' => 'Authorization',
31+
* 'example' => 'Bearer true',
32+
* 'description' => '认证令牌'
33+
* ]
34+
*/
35+
'headers' => [],
36+
37+
/**
38+
* 服务的基础 URL（服务器）。
39+
* 可以定义多个环境，例如生产环境、测试环境等。
40+
*
41+
* @type ServersStorage[] $service
42+
*/
43+
'service' => [
44+
new ServersStorage('http://127.0.0.1', 'Dev'),
45+
// 测试环境 同时增加环境变量
46+
(new ServersStorage('http://test.explore.com', 'Test'))
47+
->addVariable('admin_token', '变量说明', '123'),
48+
],
49+
50+
/**
51+
* 需要排除的扫描目录。
52+
* 这些路径是相对于项目根目录的。
53+
*
54+
* 默认排除的目录：
55+
* - /vendor
56+
* - /tests
57+
* - /migrations
58+
* 示例：
59+
* ['/sdk', '/app']
60+
*
61+
*/
62+
'exclude_dirs' => [],
63+
];
64+
```

0 commit comments

Comments
 (0)