mako / open-api
Generate routes based on OpenAPI specifications and OpenAPI specifications from code
Installs: 28 020
Dependents: 0
Suggesters: 1
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 1
Requires
- php: >=8.1.0
- cebe/php-openapi: ^1.7
- zircote/swagger-php: ^4.5
Requires (Dev)
- mako/framework: ^10.0.0-dev
- phpstan/phpstan: ^1.4.5
README
The mako/open-api
package allows you to generate a OpenApi specification using attributes or docblock annotations and to generate routes based on the specification.
Requirements
Mako 10.0 or greater.
Installation
First you'll need to install the package as a dependency to your project.
composer require mako/open-api
Next you'll need to add the package to the cli
section of the packages
configuration array in the application.php
config file.
'cli' =>
[
mako\openapi\OpenApiPackage::class,
]
And finally replace the contents of your routes.php
file with the following:
<?php use mako\openapi\http\routing\Registrar; Registrar::register( $routes, cachedRoutes: __DIR__ . '/openapi.php', openApiSpec: __DIR__ . '/openapi.yml', );
Usage
You can build an OpenApi specification using a tool like Apicurito or by documenting your code using attributes or docblock annotations. To check out the syntax head over to the zircote/swagger-php documentation.
If you want to generate a specification file based on your documentation then you can do so by running the open-api:generate-spec
command.
To generate a cached route file for production then you'll have to run the open-api:generate-routes
command.
Note that you have to set the
operationId
parameter to the fully qualified method name (e.g. app\controllers\Index::welcome) of your controller action for the route generator to work.
openapi: 3.0.2
info:
title: Mako
version: 1.0.0
description: Mako example application.
paths:
'/':
summary: Displays a welcome page.
get:
operationId: 'app\controllers\Index::welcome'