Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit ac20d27

Browse files
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)

AltStyle によって変換されたページ (->オリジナル) /