PHPackages beauty-framework/openapi-support - 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. beauty-framework/openapi-support ActiveLibrary[API Development](/categories/api) beauty-framework/openapi-support ================================ Beauty OpenAPI Support 1.0.2(1y ago)03MITPHPPHP >=8.1 Since Jun 23Pushed 1y agoCompare [ Source](https://github.com/beauty-framework/openapi-support)[ Packagist](https://packagist.org/packages/beauty-framework/openapi-support)[ RSS](/packages/beauty-framework-openapi-support/feed)WikiDiscussions main Synced today READMEChangelog (3)Dependencies (4)Versions (4)Used By (0) Beauty OpenAPI ============== [](#beauty-openapi) Modern OpenAPI 3 integration for [beauty-framework](https://github.com/beauty-framework) powered by [swagger-php](https://github.com/zircote/swagger-php) and beautiful Redoc UI out of the box. Features -------- [](#features) - ⚡️ PSR-7 compatible - 🍰 Attribute-based OpenAPI documentation (PHP 8.1+) - 🛠 Easy integration in your project - 🚀 Out-of-the-box routes for OpenAPI spec and Redoc UI - 💾 CLI command for static spec generation Installation ------------ [](#installation) Require via composer: ``` composer require beauty-framework/openapi-support ``` **Requirements:** - PHP >=8.1 - beauty-framework/cli ^1.0 (for CLI integration) - zircote/swagger-php ^5.1 (OpenAPI generator) **Dev Requirements (for testing):** - phpunit/phpunit ^12.3 - psr/container ^2.0 Quick Start ----------- [](#quick-start) 1. **Create your API controller inheriting from `BaseOpenApiController`:** ``` namespace App\Controllers; use Beauty\OpenApi\Http\Controllers\BaseOpenApiController; use OpenApi\Attributes as OAT; #[OAT\OpenApi(openapi: OAT\OpenApi::VERSION_3_1_0, security: [['bearerAuth' => []]])] #[OAT\Info( version: '1.0.0', title: 'Basic single file API', attachables: [new OAT\Attachable()] )] #[OAT\License(name: 'MIT', identifier: 'MIT')] #[OAT\Server(url: 'https://localhost/', description: 'API server')] #[OAT\SecurityScheme(securityScheme: 'bearerAuth', type: 'http', scheme: 'bearer', description: 'Basic Auth')] #[OAT\Tag(name: 'products', description: 'All about products')] #[OAT\Tag(name: 'catalog', description: 'Catalog API')] class ApiController extends BaseOpenApiController { // Everything works out of the box! } ``` 2. **Annotate your endpoints and models using [swagger-php attributes](https://github.com/zircote/swagger-php/blob/master/Examples/Attributes/README.md):** ``` use OpenApi\Attributes as OAT; #[OAT\Get(path: '/products', tags: ['products'], ...)] #[Route(method: HttpMethodsEnum::GET, path: '/products')] public function listProducts() { ... } ``` 3. **Register console commands (optional, for static generation):** Add to `config/commands.php`: ``` return array_merge( // ... \Beauty\OpenApi\Console\RegisterCommands::commands(), // ... ); ``` 4. **Access your docs at:** - `/openapi.json` for raw spec - `/docs/api` for interactive Stoplight UI (change between Swagger, Redoc, Rapid, Stoplight via `.env` `OPENAPI_MODE=`) - You can also provide your own action classes (see SpecsAction and RedocAction) if you want to use custom logic for rendering the spec or documentation page. Just typehint your custom action classes in your controller methods. Example: ``` #[Route(method: HttpMethodsEnum::GET, path: '/products')] public function openApiJson(MyCustomSpecsAction $action): ResponseInterface { return $action(); } ``` - This gives you full control over how the OpenAPI spec and documentation UI are served. Switching Documentation UI -------------------------- [](#switching-documentation-ui) You can control which documentation UI is shown at `/docs/api` by setting the `OPENAPI_MODE` variable in your `.env` file: ``` OPENAPI_MODE=stoplight # or swagger, redoc, rapid ``` **Supported values:** - stoplight (default) - swagger - redoc - rapid The selected viewer will be automatically rendered at `/docs/api` depending on this value. If you provide an invalid value, Stoplight will be used by default. Customization ------------- [](#customization) - Override `redoc()` or `openApiJson()` methods in your controller to change the output. - Redoc page can be replaced or extended as needed. How it works ------------ [](#how-it-works) - At runtime, `SpecsAction` uses `OpenApiGenerator` to scan your codebase and build the OpenAPI spec. - `RedocAction` renders a simple Redoc UI page pointing to your `/openapi.json`. - For production, you can pre-generate the spec and serve it as a static file for performance. Advanced: Static Generation --------------------------- [](#advanced-static-generation) You can generate the spec as a file using the CLI command: ``` ./beauty openapi:generate ``` This allows serving the OpenAPI spec statically in production. Under the Hood -------------- [](#under-the-hood) - Built on [zircote/swagger-php](https://github.com/zircote/swagger-php) — the de-facto OpenAPI generator for PHP. - Fully compatible with beauty/http responses. Limitations & Tips ---------------------- [](#limitations--tips) - **Static vs. Dynamic:** If you have a static `/public/openapi.json`, RoadRunner will serve it as a file instead of going through the controller. Remove the file if you want dynamic generation. - **Performance:** Generating the spec dynamically on every request can be slow on large projects. Consider using static generation for production. - **Customization:** For advanced Redoc pages, simply override the `redoc()` method. Links ----- [](#links) - [swagger-php documentation](https://github.com/zircote/swagger-php) - [OpenAPI Specification](https://swagger.io/specification/) - [Redoc Documentation](https://redocly.com/docs/redoc/) License ------- [](#license) MIT ### Health Score 28 — LowBetter than 52% of packages Maintenance49 Moderate activity, may be stable Popularity3 Limited adoption so far Community6 Small or concentrated contributor base Maturity48 Maturing project, gaining track record 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 ~2 days Total 3 Last Release 371d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/068f8c26f06f513a9c38d2a01c4d90a85eae1125a5b9d14eae7059715be860e4?d=identicon)[m1n64](/maintainers/m1n64) --- Top Contributors [![m1n64](https://avatars.githubusercontent.com/u/24874264?v=4)](https://github.com/m1n64 "m1n64 (4 commits)") --- Tags openapisupportbeauty ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/beauty-framework-openapi-support/health.svg) ``` [![Health](https://phpackages.com/badges/beauty-framework-openapi-support/health.svg)](https://phpackages.com/packages/beauty-framework-openapi-support) ``` ### Alternatives [darkaonline/l5-swagger OpenApi or Swagger integration to Laravel 3.0k37.6M134](/packages/darkaonline-l5-swagger)[darkaonline/swagger-lume OpenApi or Swagger integration to Lumen 3362.4M3](/packages/darkaonline-swagger-lume)[tobion/openapi-symfony-routing Loads routes in Symfony based on OpenAPI/Swagger annotations 4220.0k](/packages/tobion-openapi-symfony-routing)[wapmorgan/openapi-generator OpenApi configuration generator directly from PHP code (PhpDoc, functions signature and type hints) and projects (for yii2, slim, laravel). Can be used with a large monolithic backend to maintain big API documentation 212.8k](/packages/wapmorgan-openapi-generator) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)