Featrue/open api

.openapi.php

@@ -3,21 +3,47 @@
 use Astral\Serialize\OpenApi\Storage\OpenAPI\ServersStorage;
 
 return [
+    // API Document Title
     'title' => 'API Docs',
 
+    // Description of the API document
     'description' => 'API Docs description.',
 
     /**
-     * 向全局头部参数存储中添加一个的头部参数。
-     * @param string $name
-     * @param string $example
-     * @param string $description
+     * Global headers to be added to every request.
+     * Each header should include name, example, and description.
+     *
+     * Example:
+     * [
+     *     'name'        => 'Authorization',
+     *     'example'     => 'Bearer token',
+     *     'description' => 'Authentication token'
+     * ]
      */
-    'headers' => [
-
-    ],
+    'headers' => [],
 
+    /**
+     * Service base URLs (servers).
+     * You can define multiple environments like production, staging, etc.
+     *
+     * @type ServersStorage[] $service
+     */
     'service' => [
-        new ServersStorage('http://127.0.0.1','默认环境'),
+        new ServersStorage('http://127.0.0.1', 'Default Environment'),
     ],
+
+    /**
+     * Directories to exclude from scanning.
+     * These paths are relative to the project root directory.
+     *
+     * Default excluded directories:
+     * - /vendor
+     * - /tests
+     * - /migrations
+     * Example:
+     * ['/sdk', '/app']
+     *
+     * You can override or extend this list in your config file.
+     */
+    'exclude_dirs' => [],
 ];

README.md

@@ -118,3 +118,68 @@ class User extends Serialize {
     }
 }
 ```
+
+## Auto Create OpenApi Doc
+
+### Creating Request
+
+```php
+use Astral\Serialize\Serialize;
+
+class UserAddRequest extends Serialize {
+    public string $name;
+    public int $id;
+}
+
+class UserDetailRequest extends Serialize {
+    public int $id;
+}
+```
+
+### Creating Response
+```php
+use Astral\Serialize\Serialize;
+
+class UserDto extends Serialize {
+    public string $name,
+    public int $id;
+}
+```
+
+### Creating Controller
+```php
+use Astral\Serialize\Serialize;
+use Astral\Serialize\OpenApi\Enum\MethodEnum;
+
+#[\Astral\Serialize\OpenApi\Annotations\Tag('User Module Management')]
+class UserController {
+
+    #[\Astral\Serialize\OpenApi\Annotations\Summary('Create User')]
+    #[\Astral\Serialize\OpenApi\Annotations\Route('/user/create')]
+    #[\Astral\Serialize\OpenApi\Annotations\RequestBody(UserAddRequest::class)]
+     #[\Astral\Serialize\OpenApi\Annotations\Response(UserDto::class)]
+    public function create() 
+    {
+        return new UserDto(); 
+    }
+
+    #[\Astral\Serialize\OpenApi\Annotations\Summary('User Detail')]
+    #[\Astral\Serialize\OpenApi\Annotations\Route(route:'/user/detail', method: MethodEnum::GET)]
+    public function detail(UserDetailRequest $request): UserDto  
+    {
+        return new UserDto();
+    }
+}
+```
+### Starting the Service
+
+#### Docker Deployment
+
+Navigate to the project root directory first:
+
+```shell
+docker run  -v $PWD/vendor/astral/php-serialize/src/OpenApi/Frankenphp/Caddyfile:/etc/frankenphp/Caddyfile -v $PWD:/app -p 8089:80 dunglas/frankenphp
+```
+Access `http://127.0.0.1:8089/docs` to view the documentation.
+
+![UI-IMG](./docs/en/openapi/ui.png)

composer.json

@@ -21,11 +21,10 @@
         "illuminate/support": "^6.0||^7.0||^8.0||^9.0||^10.0||^11.0||^12.0",
         "phpdocumentor/reflection-docblock": "^5.5",
         "phpdocumentor/reflection": "^6.0",
-        "fakerphp/faker": "^1.23",
-        "psr/simple-cache": "^3.0",
-        "symfony/console": "^6.4"
+        "psr/simple-cache": "^3.0"
     },
     "require-dev" : {
+        "fakerphp/faker": "^1.23",
         "phpstan/phpstan": "^2.0.2",
         "friendsofphp/php-cs-fixer": "^3.0",
         "mockery/mockery": "^1.6",