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 2ea1976

Browse files
Featrue/open api (#4)
Added OpenAPI service startup functionality Added OpenAPI quick start documentation
1 parent 868e9a6 commit 2ea1976

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+2636
-3744
lines changed

‎.openapi.php

Lines changed: 34 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,47 @@
33
use Astral\Serialize\OpenApi\Storage\OpenAPI\ServersStorage;
44

55
return [
6+
// API Document Title
67
'title' => 'API Docs',
78

9+
// Description of the API document
810
'description' => 'API Docs description.',
911

1012
/**
11-
* 向全局头部参数存储中添加一个的头部参数。
12-
* @param string $name
13-
* @param string $example
14-
* @param string $description
13+
* Global headers to be added to every request.
14+
* Each header should include name, example, and description.
15+
*
16+
* Example:
17+
* [
18+
* 'name' => 'Authorization',
19+
* 'example' => 'Bearer token',
20+
* 'description' => 'Authentication token'
21+
* ]
1522
*/
16-
'headers' => [
17-
18-
],
23+
'headers' => [],
1924

25+
/**
26+
* Service base URLs (servers).
27+
* You can define multiple environments like production, staging, etc.
28+
*
29+
* @type ServersStorage[] $service
30+
*/
2031
'service' => [
21-
new ServersStorage('http://127.0.0.1','默认环境'),
32+
new ServersStorage('http://127.0.0.1','Default Environment'),
2233
],
34+
35+
/**
36+
* Directories to exclude from scanning.
37+
* These paths are relative to the project root directory.
38+
*
39+
* Default excluded directories:
40+
* - /vendor
41+
* - /tests
42+
* - /migrations
43+
* Example:
44+
* ['/sdk', '/app']
45+
*
46+
* You can override or extend this list in your config file.
47+
*/
48+
'exclude_dirs' => [],
2349
];

‎README.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,3 +118,68 @@ class User extends Serialize {
118118
}
119119
}
120120
```
121+
122+
## Auto Create OpenApi Doc
123+
124+
### Creating Request
125+
126+
```php
127+
use Astral\Serialize\Serialize;
128+
129+
class UserAddRequest extends Serialize {
130+
public string $name;
131+
public int $id;
132+
}
133+
134+
class UserDetailRequest extends Serialize {
135+
public int $id;
136+
}
137+
```
138+
139+
### Creating Response
140+
```php
141+
use Astral\Serialize\Serialize;
142+
143+
class UserDto extends Serialize {
144+
public string $name,
145+
public int $id;
146+
}
147+
```
148+
149+
### Creating Controller
150+
```php
151+
use Astral\Serialize\Serialize;
152+
use Astral\Serialize\OpenApi\Enum\MethodEnum;
153+
154+
#[\Astral\Serialize\OpenApi\Annotations\Tag('User Module Management')]
155+
class UserController {
156+
157+
#[\Astral\Serialize\OpenApi\Annotations\Summary('Create User')]
158+
#[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
159+
#[\Astral\Serialize\OpenApi\Annotations\RequestBody(UserAddRequest::class)]
160+
#[\Astral\Serialize\OpenApi\Annotations\Response(UserDto::class)]
161+
public function create()
162+
{
163+
return new UserDto();
164+
}
165+
166+
#[\Astral\Serialize\OpenApi\Annotations\Summary('User Detail')]
167+
#[\Astral\Serialize\OpenApi\Annotations\Route(route:'/user/detail', method: MethodEnum::GET)]
168+
public function detail(UserDetailRequest $request): UserDto
169+
{
170+
return new UserDto();
171+
}
172+
}
173+
```
174+
### Starting the Service
175+
176+
#### Docker Deployment
177+
178+
Navigate to the project root directory first:
179+
180+
```shell
181+
docker run -v $PWD/vendor/astral/php-serialize/src/OpenApi/Frankenphp/Caddyfile:/etc/frankenphp/Caddyfile -v $PWD:/app -p 8089:80 dunglas/frankenphp
182+
```
183+
Access `http://127.0.0.1:8089/docs` to view the documentation.
184+
185+
![UI-IMG](./docs/en/openapi/ui.png)

‎composer.json

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,11 +21,10 @@
2121
"illuminate/support": "^6.0||^7.0||^8.0||^9.0||^10.0||^11.0||^12.0",
2222
"phpdocumentor/reflection-docblock": "^5.5",
2323
"phpdocumentor/reflection": "^6.0",
24-
"fakerphp/faker": "^1.23",
25-
"psr/simple-cache": "^3.0",
26-
"symfony/console": "^6.4"
24+
"psr/simple-cache": "^3.0"
2725
},
2826
"require-dev" : {
27+
"fakerphp/faker": "^1.23",
2928
"phpstan/phpstan": "^2.0.2",
3029
"friendsofphp/php-cs-fixer": "^3.0",
3130
"mockery/mockery": "^1.6",

0 commit comments

Comments
(0)

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