Download the PHP package genai/openapi without Composer

genai/openapi

Auto-generates an OpenAPI 3 document for your JSON API and serves Swagger UI — the same compile-time-scan approach as the rest of the stack, so the docs come for free with zero runtime cost.

How it works

A build processor (OpenApiProcessor) runs during composer compile and reads the attributes you already have:

• Paths + methods ← #[Route] / #[GetMapping] / #[PostMapping] … on #[RestController] classes (HTML #[Controller]s are ignored — they're not an API).
• Path params ← {braces} in the route path.
• Request body schema ← an action's GenAI\Web\Form parameter → a component schema built from that class's fields.
• Schemas ← a #[Dto] is described by its getters and their return types (matching how the serializer emits it; nested DTOs become $refs). A request Form is described by its properties + validation constraints (anything exposing rule()): #[NotBlank]→required, #[Email]→format: email, #[Length(min/max)]→minLength/maxLength, #[Pattern]→pattern.
• Summary / description ← optional args on the mapping itself (#[GetMapping('/games', summary: '…', description: '…')]).
• Tag (groups endpoints) ← #[RestController(tag: '…', description: '…')].

The document is baked into Cache\OpenApi::json() (always emitted), and a shipped controller exposes it:

• GET /openapi.json — the spec
• GET /docs — Swagger UI (loads swagger-ui-dist from a CDN → needs internet)

Use it

Then annotate a JSON endpoint:

Open …/docs to explore. …/openapi.json is the raw document (feed it to client generators, Postman, etc.).

Notes

• Build-time, zero runtime cost — the spec is baked, like Cache\Router.
• REST only — #[Controller] (HTML/view) actions are intentionally excluded.
• Success response: point the mapping at a response DTO — #[GetMapping('/games', response: GameView::class . '[]')] (append [] for an array). The DTO is a plain documentation class; field types come from @var docblocks (props can't be typed on PHP 5.3). If no response: is given, the processor reads a declared return type (: array, : GameView) — but that's PHP 7+ syntax that breaks a 5.3 runtime, so on 5.3 use response:. Otherwise a generic 200.

• Error responses: list the statuses on the mapping with errorCodes: [...] (validated at compile time — a value outside 100–599 fails the build). Each is documented with the one shared Error component ({ code, message }), so every error in the API looks the same; the description is the standard HTTP reason phrase. Example:

• Decoupled — validation facets are read by duck-typing rule(), so it works with or without genai/validation installed.
• Swagger UI is loaded from a CDN for convenience; for an offline/CSP setup, vendor swagger-ui-dist and point the /docs page at the local assets.