PHPackages                             genai/openapi - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. genai/openapi

ActiveLibrary[API Development](/categories/api)

genai/openapi
=============

Generates an OpenAPI 3 document at build time from your #\[RestController\] routes, request-body Forms/DTOs and validation constraints — baked into a reflection-free Cache\\OpenApi — and ships a controller that serves /openapi.json and a Swagger UI page at /docs. PHP 5.3-safe at runtime.

v1.0.1(1mo ago)079↓52.1%Apache-2.0PHPPHP >=5.3.0CI passing

Since Jul 3Pushed 1mo agoCompare

[ Source](https://github.com/GenAIIO/php-openapi)[ Packagist](https://packagist.org/packages/genai/openapi)[ RSS](/packages/genai-openapi/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (3)Versions (3)Used By (0)

genai/openapi
=============

[](#genaiopenapi)

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
------------

[](#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 `$ref`s). 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
------

[](#use-it)

```
composer require genai/openapi
composer compile
```

Then annotate a JSON endpoint:

```
#[RestController(path: '/api', tag: 'KidSafe API', description: 'Public JSON endpoints.')]
class ApiController
{
    #[GetMapping('/games', summary: 'List the published games')]
    public function games() { return $this->games->all(); }       // RestController -> JSON

    #[PostMapping('/feedback', summary: 'Send feedback')]
    public function feedback(FeedbackForm $form) { ... }           // body schema from FeedbackForm
}
```

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

Notes
-----

[](#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:

    ```
    #[PostMapping('/feedback', summary: 'Send feedback', response: FeedbackResult::class, errorCodes: [422, 500])]
    public function feedback(FeedbackForm $form) { ... }
    ```
- **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.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance90

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity30

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~6 days

Total

2

Last Release

47d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/25e5bd31b5dd70d47cbdc738bded06dbabfba3d584acce63c2c4b4fb7847f39d?d=identicon)[jinnguyen](/maintainers/jinnguyen)

---

Top Contributors

[![linhnnmt](https://avatars.githubusercontent.com/u/162856460?v=4)](https://github.com/linhnnmt "linhnnmt (7 commits)")

### Embed Badge

![Health badge](/badges/genai-openapi/health.svg)

```
[![Health](https://phpackages.com/badges/genai-openapi/health.svg)](https://phpackages.com/packages/genai-openapi)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35816.5M7](/packages/exsyst-swagger)[lucasdotvin/laravel-soulbscription

A straightforward interface to handle subscriptions and features consumption.

709209.3k](/packages/lucasdotvin-laravel-soulbscription)[pimax/fb-messenger-php

Facebook Messenger Bot PHP API

313188.5k2](/packages/pimax-fb-messenger-php)[commercetools/commercetools-api-reference

6520.5k3](/packages/commercetools-commercetools-api-reference)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)