OpenAPI
Antares auto-generates an OpenAPI 3.0 specification from your controllers, request DTOs, and response DTOs. No extra configuration is required.
Endpoints
Section titled “Endpoints”Two routes are registered automatically on boot:
| Route | Description |
|---|---|
GET /openapi.json | The raw OpenAPI 3.0 spec as JSON |
GET /docs | Swagger UI, pre-configured against /openapi.json |
Swagger UI is loaded from unpkg.com, so /docs needs internet access in the browser.
Turning the Docs On or Off
Section titled “Turning the Docs On or Off”Both endpoints are public. By default they are on in every environment except APP_ENV=production. Set APP_DOCS in your .env to override that:
APP_DOCS=true # force docs on, e.g. a staging server running APP_ENV=productionAPP_DOCS=false # force docs off, e.g. locallyAPP_ENV | APP_DOCS | Docs |
|---|---|---|
local (or anything but production) | not set | on |
production | not set | off |
| any | true | on |
| any | false | off |
In production the route list is cached. Changing APP_DOCS in .env rebuilds the cache automatically. If you set it as a real server environment variable instead, run php vendor/bin/antares cache:clear after changing it.
What Gets Generated
Section titled “What Gets Generated”The spec is built entirely from your code:
- Paths & methods — derived from
#[Get],#[Post],#[Put],#[Patch],#[Delete]attributes, including the success status code - Path parameters —
{id}in the route, documented when a method argument has the same name - Query parameters — other
int,float,boolandstringarguments, read from the query string the same way the dispatcher does: required unless they have a default value, which is shown as the default. Arguments filled by a guard or#[Inject]are left out - Request body schema — any argument whose class has
#[Dto], with its validation attributes (#[Email],#[Min],#[MaxLength], etc.) as constraints - Response schema — a return type whose class has
#[ResponseDto], using its serialization attributes - Hidden fields — properties annotated with
#[Hide]are excluded from both request and response schemas - Renamed fields —
#[SerializeAs('key')]overrides are reflected in the response schema - Computed fields —
#[Computed]methods appear under the same name the serializer outputs, markedreadOnly
Schemas are built from constructor parameters, so declare DTO fields as promoted constructor properties.
Query Parameters
Section titled “Query Parameters”#[Get('/posts')]public function index(string $search, int $page = 1, bool $drafts = false): PostListResponse {}documents search as a required string, page as an optional integer with default 1, and drafts as an optional boolean with default false, matching what GET /posts?search=php&page=2 passes to the method.
Example
Section titled “Example”Given this DTO (in App\DTOs), response (in App\Responses), and controller:
#[Dto]readonly class CreatePostRequest{ public function __construct( #[NotBlank] #[MinLength(5)] public string $title,
#[NotBlank] #[MinLength(20)] public string $body,
#[In(['draft', 'published'])] public string $status = 'draft', ) {}}
#[ResponseDto(case: CaseStyle::SnakeCase)]readonly class PostResponse{ public function __construct( public int $id, public string $title, public string $body, public string $status,
#[SerializeAs('author_id')] public int $userId,
#[Hide] public string $internalNotes,
#[SerializeAs('created_at')] public string $createdAt, ) {}
#[Computed] public function excerpt(): string { return mb_strimwidth($this->body, 0, 120, '...'); }}
class PostController{ #[Post('/posts', 201)] public function store( #[Guard(JwtGuard::class)] AuthUser $user, CreatePostRequest $request, ): PostResponse {}}Antares generates (shortened to the parts this example produces):
{ "paths": { "/posts": { "post": { "summary": "Store", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App\\Responses\\PostResponse" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/App\\DTOs\\CreatePostRequest" } } } } } } }, "components": { "schemas": { "App\\DTOs\\CreatePostRequest": { "type": "object", "required": ["title", "body"], "properties": { "title": { "type": "string", "minLength": 5 }, "body": { "type": "string", "minLength": 20 }, "status": { "type": "string", "enum": ["draft", "published"] } } }, "App\\Responses\\PostResponse": { "type": "object", "required": ["id", "title", "body", "status", "author_id", "created_at", "excerpt"], "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "body": { "type": "string" }, "status": { "type": "string" }, "author_id": { "type": "integer" }, "created_at": { "type": "string" }, "excerpt": { "type": "string", "readOnly": true } } } } }}internalNotesis excluded,userIdappears asauthor_id, andexcerptis included as a read-only computed field.$useris filled by a guard, so it doesn’t appear in the spec.- The
summaryis the method name with a capital first letter, and the success response’s description is alwaysSuccess. - Schemas are named by the class’s full name (
App\DTOs\CreatePostRequest). #[NotBlank]has no OpenAPI equivalent and isn’t shown;titleandbodyarerequiredbecause they have no default.
Not Documented Yet
Section titled “Not Documented Yet”- Error responses (
400,422,401, …): only the success response is listed. - Route parameters with a regex, such as
{id:\d+}, are not recognised as path parameters. - Default values of request DTO fields.
Deprecated Routes
Section titled “Deprecated Routes”Mark a route as deprecated in the spec using #[Deprecated]:
use Antares\OpenApi\Attributes\Deprecated;use Antares\Router\Attributes\Get;
class UserController{ #[Get('/v1/users')] #[Deprecated] public function indexV1(): array {}
#[Get('/v2/users')] public function indexV2(): UserListResponse {}}