Download the PHP package bambamboole/laravel-openapi without Composer

Laravel OpenApi

This package provides tools around specification, documentation and implementation, that enable engineers to build a unified API experience.

Instead of hustling around with yaml or json files, you can use strongly-typed PHP attributes to define your API endpoints and schemas co-located to the responsible functionality. The provided attributes play hand in hand with the extended QueryBuilder from the spatie/laravel-query-builder package to provide a straight forward way of implementing the specified API endpoints.

There were five main goals in mind when creating this package:

• Reduce the needed boilerplate as much as possible
• Co-locate Endpoint spec to controllers, validation spec to request classes and schema spec to resource classes
• Do not generate from implementation, so that the schema can be used in tests for validation
• Provide more or less tight guard rails around the API implementation, so that its easy to onboard new developers
• Provide a way to generate OpenAPI schema files that can be used to test against in PHPUnit, for documentation and client generation
• Provide a web interface to easily view and try the OpenAPI documentation

How does it work?

Laravel OpenApi is built on the shoulders of giants, namely the packages zircote/swagger-php and spatie/laravel-query-builder and adds some additional features on top of it.

It enables you to manage multiple openapi schema files in a single project. The default configuration can be done via the openapi.php config file.

The package provides opinionated and straight forward PHP 8 attributes to define OpenAPI specifications directly in your controller methods and request/resource classes. The package provides a set of predefined attributes for common HTTP methods (GET, POST, PUT, PATCH, DELETE) that automatically:

• Generate endpoint documentation with proper path parameters
• Document request bodies and validation requirements
• Define response schemas and status codes
• Handle authentication and authorization responses

These attributes extract the necessary information from your code structure, reducing duplication and keeping your API documentation in sync with your implementation.

Installation

You can install the package via composer.

Usage

Resource definition

You can define your API resources using the #[OA\Schema] attribute. This allows you to specify the properties of your resource, including their types and whether they are required. The example below shows how to define a simple SalesOrder resource.

List endpoints

You can define a list endpoint using the #[ListEndpoint] attribute. This allows you to specify the path, resource class, description, and any additional parameters such as filters, sorts, and includes. The example below shows how to define a list endpoint for sales orders.

Filtering

We are leveraging the spatie/laravel-query-builder package to provide an easy filter implementation. Nevertheless, the filters are adapted to our conventions. This means, that a filter in the url always contains key, op and value. Examples are as follows:

View endpoints

You can define a view endpoint using the #[GetEndpoint] attribute. This allows you to specify the path, resource class, description, and any additional parameters such as includes. The example below shows how to define a view endpoint for a single sales order.

Defining request bodies

You can define request bodies works like defining resources, using the #[OA\Schema] attribute. It just happens on Laravels Form requests (or e.g. spatie/laravel-data objects) This allows you to specify the properties of your request body, including their types and whether they are required. The example below shows how to define a request body for creating a sales order.

Create endpoints

You can define a create endpoint using the #[PostEndpoint] attribute. This allows you to specify the path, resource class, description, and any additional parameters such as request body and response. The example below shows how to define a create endpoint for a sales order.

Update endpoints

You can define an update endpoint using the #[PutEndpoint] or #[PatchEndpoint] attribute. In general they are working in the same way as the #[PostEndpoint]. This allows you to specify the path, resource class, description, and any additional parameters such as request body and response. The example below shows how to define an update endpoint for a sales order.

Delete endpoints

You can define a delete endpoint using the #[DeleteEndpoint] attribute. This allows you to specify the path, resource class, description, and any additional parameters such as response. The example below shows how to define a delete endpoint for a sales order. The example below shows how to define a delete endpoint for a sales order. It also demonstrates how to use custom validation to ensure that only pending sales orders can be deleted. If the sales order is not pending, a validation exception is thrown with a custom message.

Configuration

After installation, you can publish the configuration file using:

This will create a config/openapi.php file with the following options:

Multiple Schemas

You can define multiple schemas in the configuration file. Each schema can have its own settings, including which folders to scan, output file, and other OpenAPI information.

To generate a specific schema, you can pass the schema name to the openapi:generate command:

Merging OpenAPI Schemas

If your project defines multiple OpenAPI schemas (for example, for different API versions or modules), you can merge them into a single specification file using the provided Artisan command.

Configuration

In your config/openapi.php, specify which schemas to merge and the output file:

• schemas: Array of schema keys defined in the schemas section to merge.
• files: (Optional) Additional OpenAPI files to include in the merge.
• output: (Optional) Path for the merged output file. Defaults to openapi_merged.yml in the project root.

Merging Schemas

Run the following Artisan command to merge the specified schemas and files:

This will generate a single merged OpenAPI file at the location specified in your configuration.

Example

Suppose you have two schemas, v1 and v2, defined in your config:

And your merge config:

After running php artisan openapi:merge, you will find the merged OpenAPI spec at openapi_merged.yml. By changing the file extion to json, it will generate a json file.

Web Interface

The package provides a web interface for viewing the OpenAPI documentation. By default, it's available at /api-docs and is protected by the web and auth middleware.

You can configure the web interface in the docs section of the configuration file:

Reusing filters

It can be very useful to reuse filters across multiple endpoints. This can be done by creating a new Attribute class that implements the FilterPropertyCollection interface. Here's an example:

You can then use this attribute in your controller methods:

Testing

Contributing

Ideas/Roadmap

Here are some ideas for future development:

• Support for other OpenAPI doc tools than Swagger UI
• Support for more OpenAPI features like callbacks, webhooks, and links
• Improved documentation generation with more examples and use cases
• Support for generating client libraries in various languages

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Credits

• Manuel Christlieb
• All Contributors

License

The MIT License (MIT). Please see License File for more information.