From e7f84c237f53e6fba52b561c906e94777d2b1acc Mon Sep 17 00:00:00 2001 From: MikeCi Date: Wed, 23 Sep 2026 09:41:29 +0800 Subject: [PATCH 1/2] fix(openapi): move root attributes into OA\OpenApi The generated openapi.yaml has no servers block at the root, and externalDocs shows up 6 times (in the 2 operations and in 4 schemas) instead of once. OA\Server and OA\ExternalDocumentation both allow operations as a parent, and they sit in the same attribute list as OA\Get, OA\Post and OA\Schema, so swagger-php puts them there instead of at the root. Nesting the root metadata in a single OA\OpenApi attribute leaves nothing to guess. The two security schemes move into OA\Components, which is where they end up in the output either way, so that part of the document is unchanged. Fixes #545 Signed-off-by: MikeCi --- src/App/src/OpenAPI.php | 34 ++++++++++++++++++++++++++-------- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/src/App/src/OpenAPI.php b/src/App/src/OpenAPI.php index 75f8f002..1c220631 100644 --- a/src/App/src/OpenAPI.php +++ b/src/App/src/OpenAPI.php @@ -9,14 +9,32 @@ use Fig\Http\Message\StatusCodeInterface; use OpenApi\Attributes as OA; -#[OA\Info(version: '1.0', title: 'Dotkernel API')] -#[OA\Server(url: 'http://api.dotkernel.localhost', description: 'Local development server')] -#[OA\SecurityScheme(securityScheme: 'AuthToken', type: 'http', in: 'header', bearerFormat: 'JWT', scheme: 'bearer')] -#[OA\SecurityScheme(securityScheme: 'ErrorReportingToken', type: 'apiKey', name: 'Error-Reporting-Token', in: 'header')] - -#[OA\ExternalDocumentation( - description: 'Dotkernel API documentation', - url: 'https://docs.dotkernel.org/api-documentation/' +#[OA\OpenApi( + info: new OA\Info(version: '1.0', title: 'Dotkernel API'), + servers: [ + new OA\Server(url: 'http://api.dotkernel.localhost', description: 'Local development server'), + ], + components: new OA\Components( + securitySchemes: [ + new OA\SecurityScheme( + securityScheme: 'AuthToken', + type: 'http', + in: 'header', + bearerFormat: 'JWT', + scheme: 'bearer' + ), + new OA\SecurityScheme( + securityScheme: 'ErrorReportingToken', + type: 'apiKey', + name: 'Error-Reporting-Token', + in: 'header' + ), + ], + ), + externalDocs: new OA\ExternalDocumentation( + description: 'Dotkernel API documentation', + url: 'https://docs.dotkernel.org/api-documentation/' + ), )] /** From 5ac01ac1e4af7bcb4415b01ad312e2f4049e007d Mon Sep 17 00:00:00 2001 From: Mike Qi Date: Wed, 30 Sep 2026 16:37:34 +0800 Subject: [PATCH 2/2] fix(openapi): address review on root attributes Drop `in` from the AuthToken scheme. Order the OA\OpenApi arguments as the constructor declares them, and add trailing commas. Signed-off-by: Mike Qi --- src/App/src/OpenAPI.php | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/src/App/src/OpenAPI.php b/src/App/src/OpenAPI.php index 1c220631..5a3588bd 100644 --- a/src/App/src/OpenAPI.php +++ b/src/App/src/OpenAPI.php @@ -14,27 +14,26 @@ servers: [ new OA\Server(url: 'http://api.dotkernel.localhost', description: 'Local development server'), ], + externalDocs: new OA\ExternalDocumentation( + description: 'Dotkernel API documentation', + url: 'https://docs.dotkernel.org/api-documentation/', + ), components: new OA\Components( securitySchemes: [ new OA\SecurityScheme( securityScheme: 'AuthToken', type: 'http', - in: 'header', bearerFormat: 'JWT', - scheme: 'bearer' + scheme: 'bearer', ), new OA\SecurityScheme( securityScheme: 'ErrorReportingToken', type: 'apiKey', name: 'Error-Reporting-Token', - in: 'header' + in: 'header', ), ], ), - externalDocs: new OA\ExternalDocumentation( - description: 'Dotkernel API documentation', - url: 'https://docs.dotkernel.org/api-documentation/' - ), )] /**