From 2ed937cd7d60e176f88acc2dbee79f842a2f92b3 Mon Sep 17 00:00:00 2001
From: rtcoder <dawidjez@gmail.com>
Date: Wed, 17 Jun 2026 20:03:13 +0200
Subject: [PATCH] Complete OpenAPI documentation support

---
 README.md                              |   3 +-
 REFACTORING.md                         |   1 +
 docs/index.html                        |  27 ++-
 src/Console/Commands/OpenApi.php       |  24 +-
 src/Console/Quality/QualityChecks.php  |  29 +--
 src/OpenApi/Attributes/Deprecated.php  |  10 +
 src/OpenApi/Attributes/Description.php |  13 ++
 src/OpenApi/Attributes/Response.php    |  16 ++
 src/OpenApi/Attributes/Schema.php      |  23 ++
 src/OpenApi/Attributes/Security.php    |  18 ++
 src/OpenApi/Attributes/Summary.php     |  13 ++
 src/OpenApi/Attributes/Tag.php         |  13 ++
 src/OpenApi/OpenApiGenerator.php       | 310 ++++++++++++++++++++++---
 src/OpenApi/OpenApiLivePage.php        | 220 ++++++++++++++++--
 src/OpenApi/OpenApiValidator.php       |  96 ++++++++
 tests/Feature/OpenApiTest.php          |  32 ++-
 tests/Fixtures/TestControllers.php     |  30 ++-
 17 files changed, 785 insertions(+), 93 deletions(-)
 create mode 100644 src/OpenApi/Attributes/Deprecated.php
 create mode 100644 src/OpenApi/Attributes/Description.php
 create mode 100644 src/OpenApi/Attributes/Response.php
 create mode 100644 src/OpenApi/Attributes/Schema.php
 create mode 100644 src/OpenApi/Attributes/Security.php
 create mode 100644 src/OpenApi/Attributes/Summary.php
 create mode 100644 src/OpenApi/Attributes/Tag.php
 create mode 100644 src/OpenApi/OpenApiValidator.php

diff --git a/README.md b/README.md
index 2fed748..b04697d 100644
--- a/README.md
+++ b/README.md
@@ -465,10 +465,11 @@ Generate OpenAPI documentation from registered routes:
 ```sh
 ./shift openapi
 ./shift openapi --output=docs/openapi.json
+./shift openapi --validate
 ./shift openapi --live
 ```
 
-The generator reads module routes from the same router used by the HTTP runtime and emits OpenAPI 3.0 JSON. Live mode starts a local documentation server at `http://127.0.0.1:8088` by default. Use `--host=` and `--port=` to change the binding.
+The generator reads module routes from the same router used by the HTTP runtime and emits OpenAPI 3.0 JSON. It understands routing attributes, parameter binding attributes, request DTO rules, response metadata, and OpenAPI attributes such as `#[Summary]`, `#[Description]`, `#[Tag]`, `#[Response]`, `#[Deprecated]`, `#[Security]`, and `#[Schema]`. Live mode starts a local documentation server at `http://127.0.0.1:8088` by default. Use `--host=` and `--port=` to change the binding.
 
 Run the example module command:
 
diff --git a/REFACTORING.md b/REFACTORING.md
index 25e3a2e..ffb9d78 100644
--- a/REFACTORING.md
+++ b/REFACTORING.md
@@ -42,6 +42,7 @@ ShiftPHP is moving toward an API-only modular monolith. View templates, compiled
 - [x] Developer documentation organized into a Laravel-like guide.
 - [x] CLI quality gate with `shift lint` and `shift qa`.
 - [x] OpenAPI JSON generation from registered module routes with `shift openapi`.
+- [x] OpenAPI documentation attributes, validation, and live Swagger-like viewer.
 - [x] Removal of view storage and example page assets from runtime.
 - [x] Removal of legacy `application/controllers` and `application/routes.php`.
 - [x] Domain-oriented framework namespaces:
diff --git a/docs/index.html b/docs/index.html
index 478c04b..0a8e171 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -694,15 +694,40 @@ <h2>OpenAPI</h2>
 
                 <pre><code>./shift openapi
 ./shift openapi --output=docs/openapi.json
+./shift openapi --validate
 ./shift openapi --live</code></pre>
 
                 <p>The generator reads route paths, HTTP methods, controller handlers, path parameters, query parameters, request body attributes, request DTO rules, response status attributes, and response header attributes.</p>
 
+                <pre><code>use Shift\OpenApi\Attributes\Description;
+use Shift\OpenApi\Attributes\Response;
+use Shift\OpenApi\Attributes\Schema;
+use Shift\OpenApi\Attributes\Security;
+use Shift\OpenApi\Attributes\Summary;
+use Shift\OpenApi\Attributes\Tag;
+
+#[Tag('Users')]
+final class UserController
+{
+    #[Summary('Create a user')]
+    #[Description('Creates a user account from a JSON request body.')]
+    #[Security('bearerAuth')]
+    #[Response(201, 'User created')]
+    public function store(
+        #[Schema(format: 'email')]
+        string $email
+    ): array {
+        return ['email' =&gt; $email];
+    }
+}</code></pre>
+
+                <p>Available OpenAPI attributes include <code>Summary</code>, <code>Description</code>, <code>Tag</code>, <code>Response</code>, <code>Deprecated</code>, <code>Security</code>, and <code>Schema</code>. Validation mode checks the generated document for required OpenAPI fields, unique operation ids, responses, and declared path parameters.</p>
+
                 <pre><code>./shift help openapi
 ./shift api:docs --output=storage/openapi.json
 ./shift openapi --live --host=127.0.0.1 --port=8088</code></pre>
 
-                <p>Live mode writes the generated JSON into a temporary directory and starts a local documentation server with a lightweight Swagger-like HTML viewer.</p>
+                <p>Live mode writes the generated JSON into a temporary directory and starts a local documentation server with a lightweight Swagger-like HTML viewer, endpoint search, tag filtering, dark mode, and JSON download.</p>
             </section>
 
             <section id="database">
diff --git a/src/Console/Commands/OpenApi.php b/src/Console/Commands/OpenApi.php
index 70b606b..6156822 100644
--- a/src/Console/Commands/OpenApi.php
+++ b/src/Console/Commands/OpenApi.php
@@ -7,6 +7,7 @@
 use Shift\Modules\ModuleLoader;
 use Shift\OpenApi\OpenApiGenerator;
 use Shift\OpenApi\OpenApiLivePage;
+use Shift\OpenApi\OpenApiValidator;
 use Shift\Routing\Router\Router;
 
 #[\Shift\Console\Attributes\Command('openapi', aliases: ['api:docs'], group: 'documentation')]
@@ -27,12 +28,31 @@ public function execute(mixed ...$args): void
 
         $outputPath = $this->outputPath($args);
         $live = $this->hasOption($args, '--live');
+        $validate = $this->hasOption($args, '--validate');
 
-        if ($outputPath === null && !$live) {
+        if ($validate) {
+            $errors = (new OpenApiValidator())->validate($document);
+
+            if ($errors !== []) {
+                $cli = new Cli();
+
+                foreach ($errors as $error) {
+                    $cli->error($error);
+                }
+
+                exit(1);
+            }
+        }
+
+        if ($outputPath === null && !$live && !$validate) {
             echo $json . PHP_EOL;
             return;
         }
 
+        if ($validate) {
+            (new Cli())->success('OpenAPI document is valid.');
+        }
+
         if ($outputPath !== null) {
             $this->writeFile($outputPath, $json . PHP_EOL);
             (new Cli())->success('OpenAPI document written to ' . $outputPath);
@@ -45,7 +65,7 @@ public function execute(mixed ...$args): void
 
     public function getHelp(): string
     {
-        return 'Usage: ./shift openapi [--output=docs/openapi.json] [--live] [--host=127.0.0.1] [--port=8088]';
+        return 'Usage: ./shift openapi [--output=docs/openapi.json] [--validate] [--live] [--host=127.0.0.1] [--port=8088]';
     }
 
     public function getDescription(): string
diff --git a/src/Console/Quality/QualityChecks.php b/src/Console/Quality/QualityChecks.php
index ffdd9c4..8534552 100644
--- a/src/Console/Quality/QualityChecks.php
+++ b/src/Console/Quality/QualityChecks.php
@@ -96,34 +96,9 @@ public function routeList(): CheckResult
 
     public function openApiDocument(): CheckResult
     {
-        $command = escapeshellarg(PHP_BINARY) . ' ' . escapeshellarg($this->projectRoot() . '/shift') . ' openapi 2>&1';
-        $previousDirectory = getcwd();
-
-        if ($previousDirectory !== false) {
-            chdir($this->projectRoot());
-        }
-
-        try {
-            exec($command, $output, $exitCode);
-        } finally {
-            if ($previousDirectory !== false) {
-                chdir($previousDirectory);
-            }
-        }
-
-        if ($exitCode !== 0) {
-            $details = trim(implode(' ', array_slice($output, -3)));
-
-            return CheckResult::fail('OpenAPI document', $details !== '' ? $details : 'Command failed with exit code ' . $exitCode);
-        }
-
-        $document = json_decode(implode("\n", $output), true);
-
-        if (!is_array($document) || ($document['openapi'] ?? null) !== '3.0.3') {
-            return CheckResult::fail('OpenAPI document', 'Generated document is not valid OpenAPI JSON');
-        }
+        $command = escapeshellarg(PHP_BINARY) . ' ' . escapeshellarg($this->projectRoot() . '/shift') . ' openapi --validate 2>&1';
 
-        return CheckResult::ok('OpenAPI document', './shift openapi passed');
+        return $this->runShellCheck('OpenAPI document', $command, './shift openapi --validate passed');
     }
 
     private function runShellCheck(string $name, string $command, string $successDetails): CheckResult
diff --git a/src/OpenApi/Attributes/Deprecated.php b/src/OpenApi/Attributes/Deprecated.php
new file mode 100644
index 0000000..19f1cfb
--- /dev/null
+++ b/src/OpenApi/Attributes/Deprecated.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Deprecated
+{
+}
diff --git a/src/OpenApi/Attributes/Description.php b/src/OpenApi/Attributes/Description.php
new file mode 100644
index 0000000..869f570
--- /dev/null
+++ b/src/OpenApi/Attributes/Description.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::TARGET_PARAMETER | Attribute::TARGET_PROPERTY)]
+class Description
+{
+    public function __construct(public readonly string $text)
+    {
+    }
+}
diff --git a/src/OpenApi/Attributes/Response.php b/src/OpenApi/Attributes/Response.php
new file mode 100644
index 0000000..6ade582
--- /dev/null
+++ b/src/OpenApi/Attributes/Response.php
@@ -0,0 +1,16 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class Response
+{
+    public function __construct(
+        public readonly int $status,
+        public readonly string $description = 'Response',
+        public readonly ?string $type = 'object'
+    ) {
+    }
+}
diff --git a/src/OpenApi/Attributes/Schema.php b/src/OpenApi/Attributes/Schema.php
new file mode 100644
index 0000000..087c650
--- /dev/null
+++ b/src/OpenApi/Attributes/Schema.php
@@ -0,0 +1,23 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_PARAMETER | Attribute::TARGET_PROPERTY)]
+class Schema
+{
+    /**
+     * @param list<string> $enum
+     */
+    public function __construct(
+        public readonly ?string $type = null,
+        public readonly ?string $format = null,
+        public readonly ?string $description = null,
+        public readonly ?string $itemsType = null,
+        public readonly array $enum = [],
+        public readonly ?bool $required = null,
+        public readonly ?bool $nullable = null
+    ) {
+    }
+}
diff --git a/src/OpenApi/Attributes/Security.php b/src/OpenApi/Attributes/Security.php
new file mode 100644
index 0000000..229214d
--- /dev/null
+++ b/src/OpenApi/Attributes/Security.php
@@ -0,0 +1,18 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class Security
+{
+    /**
+     * @param list<string> $scopes
+     */
+    public function __construct(
+        public readonly string $name,
+        public readonly array $scopes = []
+    ) {
+    }
+}
diff --git a/src/OpenApi/Attributes/Summary.php b/src/OpenApi/Attributes/Summary.php
new file mode 100644
index 0000000..9a5b7af
--- /dev/null
+++ b/src/OpenApi/Attributes/Summary.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class Summary
+{
+    public function __construct(public readonly string $text)
+    {
+    }
+}
diff --git a/src/OpenApi/Attributes/Tag.php b/src/OpenApi/Attributes/Tag.php
new file mode 100644
index 0000000..888041a
--- /dev/null
+++ b/src/OpenApi/Attributes/Tag.php
@@ -0,0 +1,13 @@
+<?php
+
+namespace Shift\OpenApi\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_CLASS | Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class Tag
+{
+    public function __construct(public readonly string $name)
+    {
+    }
+}
diff --git a/src/OpenApi/OpenApiGenerator.php b/src/OpenApi/OpenApiGenerator.php
index aed6b6d..490a191 100644
--- a/src/OpenApi/OpenApiGenerator.php
+++ b/src/OpenApi/OpenApiGenerator.php
@@ -6,8 +6,16 @@
 use ReflectionMethod;
 use ReflectionNamedType;
 use ReflectionParameter;
+use ReflectionProperty;
+use Shift\OpenApi\Attributes\Deprecated;
+use Shift\OpenApi\Attributes\Description;
+use Shift\OpenApi\Attributes\Response as OpenApiResponse;
+use Shift\OpenApi\Attributes\Schema;
+use Shift\OpenApi\Attributes\Security;
+use Shift\OpenApi\Attributes\Summary;
+use Shift\OpenApi\Attributes\Tag;
 use Shift\Response\JsonResponse;
-use Shift\Response\Response;
+use Shift\Response\Response as HttpResponse;
 use Shift\Routing\Attributes\Body;
 use Shift\Routing\Attributes\BodyDto;
 use Shift\Routing\Attributes\Header;
@@ -56,12 +64,32 @@ private function operation(Route $route): array
         $statusCode = $this->statusCode($method);
         $operation = [
             'operationId' => $this->operationId($controller, $method),
-            'tags' => [$this->tag($controller)],
-            'responses' => [
-                (string) $statusCode => $this->response($method, $statusCode),
-            ],
+            'tags' => $this->tags($controller, $method),
+            'responses' => $this->responses($method, $statusCode),
         ];
 
+        $summary = $this->summary($method);
+
+        if ($summary !== null) {
+            $operation['summary'] = $summary;
+        }
+
+        $description = $this->description($method);
+
+        if ($description !== null) {
+            $operation['description'] = $description;
+        }
+
+        if ($method->getAttributes(Deprecated::class) !== []) {
+            $operation['deprecated'] = true;
+        }
+
+        $security = $this->security($controller, $method);
+
+        if ($security !== []) {
+            $operation['security'] = $security;
+        }
+
         $parameters = $this->parameters($route, $method);
 
         if ($parameters !== []) {
@@ -77,10 +105,29 @@ private function operation(Route $route): array
         return $operation;
     }
 
-    private function response(ReflectionMethod $method, int $statusCode): array
+    private function responses(ReflectionMethod $method, int $defaultStatusCode): array
+    {
+        $responses = [];
+
+        foreach ($method->getAttributes(OpenApiResponse::class) as $attribute) {
+            /** @var OpenApiResponse $response */
+            $response = $attribute->newInstance();
+            $responses[(string) $response->status] = $this->response($method, $response->status, $response->description, $response->type);
+        }
+
+        if ($responses === []) {
+            $responses[(string) $defaultStatusCode] = $this->response($method, $defaultStatusCode);
+        }
+
+        ksort($responses);
+
+        return $responses;
+    }
+
+    private function response(ReflectionMethod $method, int $statusCode, ?string $description = null, ?string $type = null): array
     {
         $response = [
-            'description' => $this->responseDescription($statusCode),
+            'description' => $description ?? $this->responseDescription($statusCode),
         ];
 
         $headers = $this->responseHeaders($method);
@@ -89,12 +136,10 @@ private function response(ReflectionMethod $method, int $statusCode): array
             $response['headers'] = $headers;
         }
 
-        if ($statusCode !== 204 && $this->returnsJson($method)) {
+        if ($statusCode !== 204 && ($type !== null || $this->returnsJson($method))) {
             $response['content'] = [
                 'application/json' => [
-                    'schema' => [
-                        'type' => 'object',
-                    ],
+                    'schema' => $this->schemaForPhpType($type ?? 'object'),
                 ],
             ];
         }
@@ -142,7 +187,7 @@ private function parameters(Route $route, ReflectionMethod $method): array
             $queryParameter = $this->queryParameterName($parameter);
 
             if ($queryParameter !== null) {
-                $parameters[] = $this->parameter($queryParameter, 'query', $parameter, !$parameter->allowsNull() && !$parameter->isDefaultValueAvailable());
+                $parameters[] = $this->parameter($queryParameter, 'query', $parameter, $this->isRequiredParameter($parameter));
             }
         }
 
@@ -191,7 +236,7 @@ private function requestBody(ReflectionMethod $method): ?array
 
             $properties[$bodyKey] = $this->schemaForParameter($parameter);
 
-            if (!$parameter->allowsNull() && !$parameter->isDefaultValueAvailable()) {
+            if ($this->isRequiredParameter($parameter)) {
                 $required[] = $bodyKey;
             }
         }
@@ -229,9 +274,10 @@ private function schemaForDto(string $class): array
 
         if (is_subclass_of($class, RequestDto::class)) {
             foreach ($class::rules() as $field => $rules) {
-                $schema['properties'][$field] = $this->schemaForRules($rules);
+                $property = $this->dtoProperty($class, (string) $field);
+                $schema['properties'][$field] = $this->schemaForRules($rules, $property);
 
-                if ($this->rulesRequireField($rules)) {
+                if ($this->rulesRequireField($rules, $property)) {
                     $required[] = $field;
                 }
             }
@@ -244,35 +290,51 @@ private function schemaForDto(string $class): array
         return $schema;
     }
 
-    private function schemaForRules(mixed $rules): array
+    private function schemaForRules(mixed $rules, ?ReflectionProperty $property = null): array
     {
-        $rules = is_array($rules) ? $rules : explode('|', (string) $rules);
-        $rules = array_map(static fn (string $rule): string => strtolower(strtok($rule, ':') ?: $rule), $rules);
-
-        if (in_array('integer', $rules, true) || in_array('int', $rules, true)) {
-            return ['type' => 'integer'];
+        $normalizedRules = $this->normalizeRules($rules);
+        $schemaAttribute = $this->schemaAttribute($property);
+
+        if ($schemaAttribute?->type !== null) {
+            $schema = $this->schemaForPhpType($schemaAttribute->type);
+        } elseif ($property !== null && $property->getType() instanceof ReflectionNamedType) {
+            $schema = $this->schemaForPhpType($property->getType()->getName());
+        } elseif (in_array('integer', $normalizedRules, true) || in_array('int', $normalizedRules, true)) {
+            $schema = ['type' => 'integer'];
+        } elseif (in_array('numeric', $normalizedRules, true) || in_array('float', $normalizedRules, true)) {
+            $schema = ['type' => 'number'];
+        } elseif (in_array('boolean', $normalizedRules, true) || in_array('bool', $normalizedRules, true)) {
+            $schema = ['type' => 'boolean'];
+        } elseif (in_array('array', $normalizedRules, true)) {
+            $schema = ['type' => 'array', 'items' => ['type' => $schemaAttribute?->itemsType ?? 'string']];
+        } else {
+            $schema = ['type' => 'string'];
         }
 
-        if (in_array('numeric', $rules, true) || in_array('float', $rules, true)) {
-            return ['type' => 'number'];
+        if (in_array('email', $normalizedRules, true)) {
+            $schema['format'] = 'email';
         }
 
-        if (in_array('boolean', $rules, true) || in_array('bool', $rules, true)) {
-            return ['type' => 'boolean'];
+        if (in_array('date', $normalizedRules, true)) {
+            $schema['format'] = 'date';
         }
 
-        if (in_array('array', $rules, true)) {
-            return ['type' => 'array', 'items' => ['type' => 'string']];
+        if (in_array('datetime', $normalizedRules, true) || in_array('date_time', $normalizedRules, true)) {
+            $schema['format'] = 'date-time';
         }
 
-        return ['type' => 'string'];
+        return $this->applySchemaAttribute($schema, $schemaAttribute);
     }
 
-    private function rulesRequireField(mixed $rules): bool
+    private function rulesRequireField(mixed $rules, ?ReflectionProperty $property = null): bool
     {
-        $rules = is_array($rules) ? $rules : explode('|', (string) $rules);
+        $schemaAttribute = $this->schemaAttribute($property);
 
-        return in_array('required', array_map('strtolower', $rules), true);
+        if ($schemaAttribute?->required !== null) {
+            return $schemaAttribute->required;
+        }
+
+        return in_array('required', $this->normalizeRules($rules), true);
     }
 
     private function bodyDtoClass(ReflectionParameter $parameter): ?string
@@ -346,27 +408,42 @@ private function parameter(string $name, string $in, ReflectionParameter $parame
             'in' => $in,
             'required' => $required,
             'schema' => $this->schemaForParameter($parameter),
-        ];
+        ] + $this->descriptionFragment($parameter);
     }
 
     private function schemaForParameter(ReflectionParameter $parameter): array
     {
+        $schemaAttribute = $this->schemaAttribute($parameter);
+
+        if ($schemaAttribute?->type !== null) {
+            return $this->applySchemaAttribute($this->schemaForPhpType($schemaAttribute->type), $schemaAttribute);
+        }
+
         $type = $parameter->getType();
 
         if (!$type instanceof ReflectionNamedType) {
-            return ['type' => 'string'];
+            return $this->applySchemaAttribute(['type' => 'string'], $schemaAttribute);
         }
 
-        return $this->schemaForPhpType($type->getName());
+        $schema = $this->schemaForPhpType($type->getName());
+
+        if ($parameter->allowsNull()) {
+            $schema['nullable'] = true;
+        }
+
+        return $this->applySchemaAttribute($schema, $schemaAttribute);
     }
 
     private function schemaForPhpType(string $type): array
     {
         return match (ltrim($type, '\\')) {
-            'int' => ['type' => 'integer'],
-            'float' => ['type' => 'number'],
-            'bool' => ['type' => 'boolean'],
+            'int', 'integer' => ['type' => 'integer'],
+            'float', 'number' => ['type' => 'number'],
+            'bool', 'boolean' => ['type' => 'boolean'],
+            'string' => ['type' => 'string'],
+            'object' => ['type' => 'object'],
             'array' => ['type' => 'array', 'items' => ['type' => 'string']],
+            'DateTimeInterface', 'DateTimeImmutable', 'DateTime' => ['type' => 'string', 'format' => 'date-time'],
             default => ['type' => 'string'],
         };
     }
@@ -398,7 +475,7 @@ private function returnsJson(ReflectionMethod $method): bool
         return $name === 'array'
             || $name === JsonResponse::class
             || is_subclass_of($name, JsonResponse::class)
-            || $name !== Response::class;
+            || $name !== HttpResponse::class;
     }
 
     private function responseDescription(int $statusCode): string
@@ -443,4 +520,161 @@ private function tag(ReflectionClass $controller): string
     {
         return preg_replace('/Controller$/', '', $controller->getShortName()) ?: $controller->getShortName();
     }
+
+    /**
+     * @return list<string>
+     */
+    private function tags(ReflectionClass $controller, ReflectionMethod $method): array
+    {
+        $tags = [];
+
+        foreach ([$controller, $method] as $reflection) {
+            foreach ($reflection->getAttributes(Tag::class) as $attribute) {
+                /** @var Tag $tag */
+                $tag = $attribute->newInstance();
+                $tags[] = $tag->name;
+            }
+        }
+
+        return array_values(array_unique($tags !== [] ? $tags : [$this->tag($controller)]));
+    }
+
+    /**
+     * @return list<array<string, list<string>>>
+     */
+    private function security(ReflectionClass $controller, ReflectionMethod $method): array
+    {
+        $security = [];
+
+        foreach ([$controller, $method] as $reflection) {
+            foreach ($reflection->getAttributes(Security::class) as $attribute) {
+                /** @var Security $item */
+                $item = $attribute->newInstance();
+                $security[] = [$item->name => $item->scopes];
+            }
+        }
+
+        return $security;
+    }
+
+    private function summary(ReflectionMethod $method): ?string
+    {
+        $attributes = $method->getAttributes(Summary::class);
+
+        if ($attributes === []) {
+            return null;
+        }
+
+        /** @var Summary $summary */
+        $summary = $attributes[0]->newInstance();
+
+        return $summary->text;
+    }
+
+    private function description(ReflectionMethod $method): ?string
+    {
+        $attributes = $method->getAttributes(Description::class);
+
+        if ($attributes === []) {
+            return null;
+        }
+
+        /** @var Description $description */
+        $description = $attributes[0]->newInstance();
+
+        return $description->text;
+    }
+
+    private function descriptionFragment(ReflectionParameter $parameter): array
+    {
+        $attributes = $parameter->getAttributes(Description::class);
+
+        if ($attributes === []) {
+            return [];
+        }
+
+        /** @var Description $description */
+        $description = $attributes[0]->newInstance();
+
+        return ['description' => $description->text];
+    }
+
+    private function isRequiredParameter(ReflectionParameter $parameter): bool
+    {
+        $schemaAttribute = $this->schemaAttribute($parameter);
+
+        if ($schemaAttribute?->required !== null) {
+            return $schemaAttribute->required;
+        }
+
+        return !$parameter->allowsNull() && !$parameter->isDefaultValueAvailable();
+    }
+
+    private function schemaAttribute(ReflectionParameter|ReflectionProperty|null $reflection): ?Schema
+    {
+        if ($reflection === null) {
+            return null;
+        }
+
+        $attributes = $reflection->getAttributes(Schema::class);
+
+        if ($attributes === []) {
+            return null;
+        }
+
+        /** @var Schema $schema */
+        $schema = $attributes[0]->newInstance();
+
+        return $schema;
+    }
+
+    private function applySchemaAttribute(array $schema, ?Schema $attribute): array
+    {
+        if ($attribute === null) {
+            return $schema;
+        }
+
+        if ($attribute->format !== null) {
+            $schema['format'] = $attribute->format;
+        }
+
+        if ($attribute->description !== null) {
+            $schema['description'] = $attribute->description;
+        }
+
+        if ($attribute->itemsType !== null && ($schema['type'] ?? null) === 'array') {
+            $schema['items'] = ['type' => $attribute->itemsType];
+        }
+
+        if ($attribute->enum !== []) {
+            $schema['enum'] = $attribute->enum;
+        }
+
+        if ($attribute->nullable !== null) {
+            $schema['nullable'] = $attribute->nullable;
+        }
+
+        return $schema;
+    }
+
+    private function dtoProperty(string $class, string $field): ?ReflectionProperty
+    {
+        if (!class_exists($class)) {
+            return null;
+        }
+
+        $reflection = new ReflectionClass($class);
+
+        return $reflection->hasProperty($field) ? $reflection->getProperty($field) : null;
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function normalizeRules(mixed $rules): array
+    {
+        $rules = is_array($rules) ? $rules : explode('|', (string) $rules);
+
+        return array_map(static fn (string $rule): string => strtolower(strtok($rule, ':') ?: $rule), $rules);
+    }
 }
diff --git a/src/OpenApi/OpenApiLivePage.php b/src/OpenApi/OpenApiLivePage.php
index 7e703ab..bb16e50 100644
--- a/src/OpenApi/OpenApiLivePage.php
+++ b/src/OpenApi/OpenApiLivePage.php
@@ -8,13 +8,14 @@ public function render(): string
     {
         return <<<'HTML'
 <!doctype html>
-<html lang="en">
+<html lang="en" data-theme="light">
 <head>
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <title>ShiftPHP OpenAPI</title>
     <style>
-        :root {
+        :root,
+        [data-theme="light"] {
             color-scheme: light;
             --bg: #f7f9fc;
             --panel: #ffffff;
@@ -22,6 +23,8 @@ public function render(): string
             --muted: #657386;
             --line: #d9e1ea;
             --accent: #d43c2f;
+            --code-bg: #101827;
+            --code-text: #f8fafc;
             --get: #0f7b6c;
             --post: #1f63b5;
             --put: #9a6700;
@@ -29,6 +32,18 @@ public function render(): string
             --delete: #b42318;
         }
 
+        [data-theme="dark"] {
+            color-scheme: dark;
+            --bg: #0f1419;
+            --panel: #151d26;
+            --text: #e7edf4;
+            --muted: #a9b5c2;
+            --line: #2b3745;
+            --accent: #f26a5b;
+            --code-bg: #070b10;
+            --code-text: #f4f7fb;
+        }
+
         * {
             box-sizing: border-box;
         }
@@ -47,6 +62,13 @@ public function render(): string
             background: var(--panel);
         }
 
+        .topbar {
+            display: flex;
+            align-items: flex-start;
+            justify-content: space-between;
+            gap: 1rem;
+        }
+
         h1 {
             margin: 0 0 0.35rem;
             font-size: 2rem;
@@ -58,10 +80,59 @@ public function render(): string
             color: var(--muted);
         }
 
+        button,
+        .download {
+            display: inline-flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 2.25rem;
+            padding: 0.4rem 0.65rem;
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            background: var(--panel);
+            color: var(--text);
+            cursor: pointer;
+            font: inherit;
+            text-decoration: none;
+        }
+
+        button:hover,
+        .download:hover {
+            border-color: var(--accent);
+        }
+
         main {
             max-width: 1120px;
             margin: 0 auto;
-            padding: 2rem 1rem 4rem;
+            padding: 1.25rem 1rem 4rem;
+        }
+
+        .toolbar {
+            display: grid;
+            grid-template-columns: minmax(0, 1fr) minmax(9rem, 14rem) auto;
+            gap: 0.75rem;
+            position: sticky;
+            top: 0;
+            z-index: 1;
+            padding: 0.75rem 0;
+            background: var(--bg);
+        }
+
+        input,
+        select {
+            width: 100%;
+            min-height: 2.4rem;
+            padding: 0.45rem 0.65rem;
+            border: 1px solid var(--line);
+            border-radius: 8px;
+            background: var(--panel);
+            color: var(--text);
+            font: inherit;
+        }
+
+        .meta {
+            margin: 0 0 1rem;
+            color: var(--muted);
         }
 
         .operation {
@@ -72,8 +143,13 @@ public function render(): string
             overflow: hidden;
         }
 
+        .operation[hidden] {
+            display: none;
+        }
+
         .operation summary {
-            display: flex;
+            display: grid;
+            grid-template-columns: 4.6rem minmax(0, 1fr) auto;
             align-items: center;
             gap: 0.75rem;
             padding: 1rem;
@@ -81,7 +157,6 @@ public function render(): string
         }
 
         .method {
-            min-width: 4.6rem;
             padding: 0.25rem 0.5rem;
             border-radius: 4px;
             color: #ffffff;
@@ -96,12 +171,20 @@ public function render(): string
         .patch { background: var(--patch); }
         .delete { background: var(--delete); }
 
-        .path {
+        .path,
+        .operation-id {
             font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-            font-size: 0.95rem;
             overflow-wrap: anywhere;
         }
 
+        .tag {
+            padding: 0.15rem 0.4rem;
+            border-radius: 999px;
+            background: var(--bg);
+            color: var(--muted);
+            font-size: 0.78rem;
+        }
+
         .details {
             padding: 0 1rem 1rem;
             border-top: 1px solid var(--line);
@@ -138,27 +221,74 @@ public function render(): string
             overflow-x: auto;
             padding: 1rem;
             border-radius: 8px;
-            background: #101827;
-            color: #f8fafc;
+            background: var(--code-bg);
+            color: var(--code-text);
         }
 
         .empty {
             padding: 1rem;
             color: var(--muted);
         }
+
+        @media (max-width: 720px) {
+            .topbar,
+            .toolbar,
+            .operation summary {
+                display: block;
+            }
+
+            .toolbar > * {
+                margin-bottom: 0.75rem;
+            }
+
+            .method,
+            .tag {
+                display: inline-block;
+                margin-bottom: 0.5rem;
+            }
+        }
     </style>
 </head>
 <body>
     <header>
-        <h1 id="title">ShiftPHP OpenAPI</h1>
-        <p id="subtitle">Loading OpenAPI document...</p>
+        <div class="topbar">
+            <div>
+                <h1 id="title">ShiftPHP OpenAPI</h1>
+                <p id="subtitle">Loading OpenAPI document...</p>
+            </div>
+            <button type="button" id="theme">Dark theme</button>
+        </div>
     </header>
-    <main id="app"></main>
+    <main>
+        <div class="toolbar">
+            <input id="search" type="search" placeholder="Search endpoints">
+            <select id="tagFilter" aria-label="Filter by tag">
+                <option value="">All tags</option>
+            </select>
+            <a class="download" href="openapi.json" download>Download JSON</a>
+        </div>
+        <p class="meta" id="meta"></p>
+        <div id="app"></div>
+    </main>
 
     <script>
         const app = document.querySelector('#app');
         const title = document.querySelector('#title');
         const subtitle = document.querySelector('#subtitle');
+        const meta = document.querySelector('#meta');
+        const search = document.querySelector('#search');
+        const tagFilter = document.querySelector('#tagFilter');
+        const theme = document.querySelector('#theme');
+        let allOperations = [];
+
+        theme.addEventListener('click', () => {
+            const next = document.documentElement.dataset.theme === 'dark' ? 'light' : 'dark';
+            document.documentElement.dataset.theme = next;
+            theme.textContent = next === 'dark' ? 'Light theme' : 'Dark theme';
+        });
+
+        search.addEventListener('input', applyFilters);
+        tagFilter.addEventListener('change', applyFilters);
 
         fetch('openapi.json')
             .then(response => response.json())
@@ -170,39 +300,52 @@ public function render(): string
 
         function render(document) {
             title.textContent = document.info?.title || 'ShiftPHP OpenAPI';
-            subtitle.textContent = `OpenAPI ${document.openapi || ''} · ${document.info?.version || ''}`;
+            subtitle.textContent = `OpenAPI ${document.openapi || ''} - ${document.info?.version || ''}`;
 
             const paths = document.paths || {};
-            const operations = [];
+            allOperations = [];
 
             Object.keys(paths).sort().forEach(path => {
                 Object.keys(paths[path]).sort().forEach(method => {
-                    operations.push({ path, method, operation: paths[path][method] });
+                    allOperations.push({ path, method, operation: paths[path][method] });
                 });
             });
 
-            if (operations.length === 0) {
+            const tags = [...new Set(allOperations.flatMap(item => item.operation.tags || []))].sort();
+            tagFilter.innerHTML = '<option value="">All tags</option>' + tags.map(tag => `<option value="${escapeHtml(tag)}">${escapeHtml(tag)}</option>`).join('');
+
+            if (allOperations.length === 0) {
                 app.innerHTML = '<p class="empty">No operations found.</p>';
+                meta.textContent = '0 operations';
                 return;
             }
 
-            app.innerHTML = operations.map(renderOperation).join('');
+            app.innerHTML = allOperations.map(renderOperation).join('');
+            applyFilters();
         }
 
         function renderOperation(item) {
             const operation = item.operation;
             const parameters = operation.parameters || [];
             const responses = operation.responses || {};
+            const tag = (operation.tags || [])[0] || 'default';
+            const summary = operation.summary ? `<p>${escapeHtml(operation.summary)}</p>` : '';
+            const description = operation.description ? `<p>${escapeHtml(operation.description)}</p>` : '';
 
             return `
-                <details class="operation" open>
+                <details class="operation" open data-path="${escapeHtml(item.path)}" data-method="${escapeHtml(item.method)}" data-tag="${escapeHtml(tag)}" data-operation="${escapeHtml(operation.operationId || '')}">
                     <summary>
                         <span class="method ${item.method}">${item.method}</span>
                         <span class="path">${escapeHtml(item.path)}</span>
+                        <span class="tag">${escapeHtml(tag)}</span>
                     </summary>
                     <div class="details">
                         <h2>Operation</h2>
-                        <p><code>${escapeHtml(operation.operationId || '')}</code></p>
+                        <p class="operation-id"><code>${escapeHtml(operation.operationId || '')}</code></p>
+                        ${summary}
+                        ${description}
+                        ${operation.deprecated ? '<p><strong>Deprecated</strong></p>' : ''}
+                        ${renderSecurity(operation.security)}
                         ${renderParameters(parameters)}
                         ${renderRequestBody(operation.requestBody)}
                         ${renderResponses(responses)}
@@ -211,6 +354,36 @@ function renderOperation(item) {
             `;
         }
 
+        function applyFilters() {
+            const query = search.value.trim().toLowerCase();
+            const tag = tagFilter.value;
+            let visible = 0;
+
+            document.querySelectorAll('.operation').forEach(operation => {
+                const haystack = [
+                    operation.dataset.path,
+                    operation.dataset.method,
+                    operation.dataset.operation,
+                    operation.dataset.tag,
+                ].join(' ').toLowerCase();
+                const matchesSearch = query === '' || haystack.includes(query);
+                const matchesTag = tag === '' || operation.dataset.tag === tag;
+                const show = matchesSearch && matchesTag;
+                operation.hidden = !show;
+                visible += show ? 1 : 0;
+            });
+
+            meta.textContent = `${visible} of ${allOperations.length} operations`;
+        }
+
+        function renderSecurity(security) {
+            if (!security || security.length === 0) {
+                return '';
+            }
+
+            return `<h2>Security</h2><pre>${escapeHtml(JSON.stringify(security, null, 2))}</pre>`;
+        }
+
         function renderParameters(parameters) {
             if (parameters.length === 0) {
                 return '';
@@ -221,14 +394,14 @@ function renderParameters(parameters) {
                     <td><code>${escapeHtml(parameter.name)}</code></td>
                     <td>${escapeHtml(parameter.in)}</td>
                     <td>${parameter.required ? 'yes' : 'no'}</td>
-                    <td>${escapeHtml(parameter.schema?.type || 'string')}</td>
+                    <td>${escapeHtml(schemaLabel(parameter.schema || {}))}</td>
                 </tr>
             `).join('');
 
             return `
                 <h2>Parameters</h2>
                 <table>
-                    <thead><tr><th>Name</th><th>In</th><th>Required</th><th>Type</th></tr></thead>
+                    <thead><tr><th>Name</th><th>In</th><th>Required</th><th>Schema</th></tr></thead>
                     <tbody>${rows}</tbody>
                 </table>
             `;
@@ -262,6 +435,11 @@ function renderResponses(responses) {
             `;
         }
 
+        function schemaLabel(schema) {
+            const type = schema.type || 'string';
+            return schema.format ? `${type}:${schema.format}` : type;
+        }
+
         function escapeHtml(value) {
             return String(value)
                 .replaceAll('&', '&amp;')
diff --git a/src/OpenApi/OpenApiValidator.php b/src/OpenApi/OpenApiValidator.php
new file mode 100644
index 0000000..8296b82
--- /dev/null
+++ b/src/OpenApi/OpenApiValidator.php
@@ -0,0 +1,96 @@
+<?php
+
+namespace Shift\OpenApi;
+
+final class OpenApiValidator
+{
+    /**
+     * @return list<string>
+     */
+    public function validate(array $document): array
+    {
+        $errors = [];
+
+        if (($document['openapi'] ?? null) !== '3.0.3') {
+            $errors[] = 'Document must use OpenAPI 3.0.3.';
+        }
+
+        if (!is_array($document['info'] ?? null) || !is_string($document['info']['title'] ?? null)) {
+            $errors[] = 'Document info.title is required.';
+        }
+
+        if (!is_array($document['paths'] ?? null)) {
+            $errors[] = 'Document paths object is required.';
+
+            return $errors;
+        }
+
+        $operationIds = [];
+
+        foreach ($document['paths'] as $path => $operations) {
+            if (!is_string($path) || !str_starts_with($path, '/')) {
+                $errors[] = 'Path must start with /: ' . (string) $path;
+                continue;
+            }
+
+            if (!is_array($operations) || $operations === []) {
+                $errors[] = 'Path has no operations: ' . $path;
+                continue;
+            }
+
+            foreach ($operations as $method => $operation) {
+                if (!is_array($operation)) {
+                    $errors[] = strtoupper((string) $method) . ' ' . $path . ' operation must be an object.';
+                    continue;
+                }
+
+                $operationId = $operation['operationId'] ?? null;
+
+                if (!is_string($operationId) || $operationId === '') {
+                    $errors[] = strtoupper((string) $method) . ' ' . $path . ' operationId is required.';
+                } elseif (isset($operationIds[$operationId])) {
+                    $errors[] = 'Duplicate operationId: ' . $operationId;
+                } else {
+                    $operationIds[$operationId] = true;
+                }
+
+                if (!is_array($operation['responses'] ?? null) || $operation['responses'] === []) {
+                    $errors[] = strtoupper((string) $method) . ' ' . $path . ' must define at least one response.';
+                }
+
+                foreach ($this->pathParameters($path) as $parameter) {
+                    if (!$this->hasPathParameter($operation['parameters'] ?? [], $parameter)) {
+                        $errors[] = strtoupper((string) $method) . ' ' . $path . ' is missing path parameter ' . $parameter . '.';
+                    }
+                }
+            }
+        }
+
+        return $errors;
+    }
+
+    /**
+     * @return list<string>
+     */
+    private function pathParameters(string $path): array
+    {
+        preg_match_all('/\{([a-zA-Z_][a-zA-Z0-9_]*)}/', $path, $matches);
+
+        return $matches[1] ?? [];
+    }
+
+    private function hasPathParameter(mixed $parameters, string $name): bool
+    {
+        if (!is_array($parameters)) {
+            return false;
+        }
+
+        foreach ($parameters as $parameter) {
+            if (($parameter['name'] ?? null) === $name && ($parameter['in'] ?? null) === 'path') {
+                return true;
+            }
+        }
+
+        return false;
+    }
+}
diff --git a/tests/Feature/OpenApiTest.php b/tests/Feature/OpenApiTest.php
index 00c7964..cdb243e 100644
--- a/tests/Feature/OpenApiTest.php
+++ b/tests/Feature/OpenApiTest.php
@@ -4,6 +4,7 @@
 use Shift\Console\CommandRegistry;
 use Shift\OpenApi\OpenApiGenerator;
 use Shift\OpenApi\OpenApiLivePage;
+use Shift\OpenApi\OpenApiValidator;
 use Shift\Routing\AttributeRouteLoader;
 use Shift\Routing\Router\Router;
 
@@ -27,22 +28,31 @@
         assertArrayHasKeyValue('operationId', 'testAttributeControllerApi', $document['paths']['/test/api/{argument}']['get'], 'Path operation should include operation id.');
 
         $getOperation = $document['paths']['/test/api/{argument}']['get'];
+        assertSameValue(['Testing'], $getOperation['tags'], 'OpenAPI tag attribute should be documented.');
+        assertSameValue('Show test argument', $getOperation['summary'], 'OpenAPI summary attribute should be documented.');
+        assertStringContains('path and query', $getOperation['description'], 'OpenAPI description attribute should be documented.');
+        assertSameValue([['bearerAuth' => []]], $getOperation['security'], 'OpenAPI security attribute should be documented.');
         assertSameValue('path', $getOperation['parameters'][0]['in'], 'Path parameter should be documented.');
         assertSameValue('argument', $getOperation['parameters'][0]['name'], 'Path parameter name should be documented.');
         assertSameValue(true, $getOperation['parameters'][0]['required'], 'Path parameter should be required.');
+        assertSameValue('Argument from the path.', $getOperation['parameters'][0]['description'], 'Parameter description should be documented.');
         assertSameValue('query', $getOperation['parameters'][1]['in'], 'Query parameter should be documented.');
         assertSameValue('include', $getOperation['parameters'][1]['name'], 'Query parameter name should be documented.');
+        assertSameValue(['meta', 'details'], $getOperation['parameters'][1]['schema']['enum'], 'Parameter enum should be documented.');
 
         $createdOperation = $document['paths']['/test/created']['post'];
-        assertArrayHasKeyValue('description', 'Created', $createdOperation['responses']['201'], 'Status attribute should set response code.');
+        assertArrayHasKeyValue('description', 'Test resource created', $createdOperation['responses']['201'], 'OpenAPI response attribute should set response description.');
         assertSameValue('created', $createdOperation['responses']['201']['headers']['X-Test']['schema']['example'], 'Header attribute should be documented.');
         assertSameValue('string', $createdOperation['requestBody']['content']['application/json']['schema']['properties']['name']['type'], 'Body parameter should be documented.');
+        assertSameValue('Display name.', $createdOperation['requestBody']['content']['application/json']['schema']['properties']['name']['description'], 'Body schema description should be documented.');
 
         $dtoOperation = $document['paths']['/dto/users']['post'];
         $dtoSchema = $dtoOperation['requestBody']['content']['application/json']['schema'];
         assertSameValue('string', $dtoSchema['properties']['email']['type'], 'DTO string field should be documented.');
+        assertSameValue('email', $dtoSchema['properties']['email']['format'], 'DTO schema format should be documented.');
         assertSameValue('integer', $dtoSchema['properties']['age']['type'], 'DTO int field should be documented.');
         assertSameValue(['email', 'age'], $dtoSchema['required'], 'DTO required fields should be documented.');
+        assertSameValue(true, $document['paths']['/dto/implicit']['post']['deprecated'], 'Deprecated operations should be documented.');
     },
     'openapi command writes output file' => function (): void {
         $root = sys_get_temp_dir() . '/shift-openapi-' . bin2hex(random_bytes(6));
@@ -70,6 +80,9 @@
         assertStringContains('ShiftPHP OpenAPI', $html, 'Live page should include the OpenAPI title.');
         assertStringContains("fetch('openapi.json')", $html, 'Live page should load generated OpenAPI JSON.');
         assertStringContains('Responses', $html, 'Live page should render response sections.');
+        assertStringContains('Search endpoints', $html, 'Live page should include endpoint search.');
+        assertStringContains('All tags', $html, 'Live page should include tag filtering.');
+        assertStringContains('Dark theme', $html, 'Live page should include theme toggle.');
     },
     'openapi help documents live server options' => function (): void {
         ob_start();
@@ -79,5 +92,22 @@
         assertStringContains('--live', $output, 'OpenAPI help should document live mode.');
         assertStringContains('--host=127.0.0.1', $output, 'OpenAPI help should document host option.');
         assertStringContains('--port=8088', $output, 'OpenAPI help should document port option.');
+        assertStringContains('--validate', $output, 'OpenAPI help should document validate option.');
+    },
+    'openapi validator reports valid and invalid documents' => function (): void {
+        $router = new Router();
+        (new AttributeRouteLoader())->load($router, [
+            TestAttributeController::class,
+        ]);
+
+        $document = (new OpenApiGenerator())->generate($router);
+        $validator = new OpenApiValidator();
+
+        assertSameValue([], $validator->validate($document), 'Generated OpenAPI document should be valid.');
+
+        unset($document['paths']['/test/api/{argument}']['get']['parameters']);
+        $errors = $validator->validate($document);
+
+        assertStringContains('missing path parameter argument', implode("\n", $errors), 'Validator should report missing path parameters.');
     },
 ];
diff --git a/tests/Fixtures/TestControllers.php b/tests/Fixtures/TestControllers.php
index f1946a1..94eb48e 100644
--- a/tests/Fixtures/TestControllers.php
+++ b/tests/Fixtures/TestControllers.php
@@ -5,6 +5,13 @@
 use Shift\Auth\AuthorizerInterface;
 use Shift\Controller;
 use Shift\Middleware\MiddlewareInterface;
+use Shift\OpenApi\Attributes\Deprecated as OpenApiDeprecated;
+use Shift\OpenApi\Attributes\Description as OpenApiDescription;
+use Shift\OpenApi\Attributes\Response as OpenApiResponse;
+use Shift\OpenApi\Attributes\Schema as OpenApiSchema;
+use Shift\OpenApi\Attributes\Security as OpenApiSecurity;
+use Shift\OpenApi\Attributes\Summary as OpenApiSummary;
+use Shift\OpenApi\Attributes\Tag as OpenApiTag;
 use Shift\Request;
 use Shift\Response\JsonResponse;
 use Shift\Response\Response;
@@ -20,10 +27,21 @@
 use Shift\Validation\RequestDto;
 
 #[RoutePrefix('/test')]
+#[OpenApiTag('Testing')]
 final class TestAttributeController extends Controller
 {
     #[Get('/api/{argument}')]
-    public function api(#[PathParam] ?string $argument = null, #[QueryParam('include')] ?string $include = null): JsonResponse
+    #[OpenApiSummary('Show test argument')]
+    #[OpenApiDescription('Returns path and query parameter details for OpenAPI tests.')]
+    #[OpenApiSecurity('bearerAuth')]
+    public function api(
+        #[PathParam]
+        #[OpenApiDescription('Argument from the path.')]
+        ?string $argument = null,
+        #[QueryParam('include')]
+        #[OpenApiSchema(enum: ['meta', 'details'], nullable: true)]
+        ?string $include = null
+    ): JsonResponse
     {
         $arguments = [];
         if ($argument !== null) {
@@ -42,7 +60,12 @@ public function api(#[PathParam] ?string $argument = null, #[QueryParam('include
     #[Post('/created')]
     #[Status(201)]
     #[Header('X-Test', 'created')]
-    public function created(#[Body('name')] string $name): array
+    #[OpenApiResponse(201, 'Test resource created')]
+    public function created(
+        #[Body('name')]
+        #[OpenApiSchema(description: 'Display name.')]
+        string $name
+    ): array
     {
         return [
             'name' => $name,
@@ -100,7 +123,9 @@ public function service(): JsonResponse
 final class CreateUserDto extends RequestDto
 {
     public function __construct(
+        #[OpenApiSchema(format: 'email', description: 'User email address.')]
         public readonly string $email,
+        #[OpenApiSchema(type: 'integer', description: 'User age.')]
         public readonly int $age
     ) {
     }
@@ -127,6 +152,7 @@ public function create(#[BodyDto] CreateUserDto $dto): array
     }
 
     #[Post('/implicit')]
+    #[OpenApiDeprecated]
     public function implicit(CreateUserDto $dto): array
     {
         return [