rogervila / openapi-laravel
Validate HTTP Requests and Responses with OpenAPI Specs
Requires
- laravel/framework: ^9.21.0
- league/openapi-psr7-validator: ^0.18.0
- nyholm/psr7: ^1.5
- symfony/cache: ^6.0
- symfony/psr-http-message-bridge: ^2.1
Requires (Dev)
- phpstan/phpstan: ^1.0
- phpunit/phpunit: ^9.0
- vimeo/psalm: ^5.0
This package is auto-updated.
Last update: 2024-10-13 15:49:23 UTC
README
OpenAPI Laravel
About
Validate HTTP Requests and Responses with OpenAPI Specs.
Install
Require the package with composer.
composer require rogervila/openapi-laravel
Laravel will autodiscover the service provider located in \LaravelOpenAPI\ServiceProvider
.
Setup
The package handles HTTP requests via Specification and Request classes.
OpenAPI Specifications
First, create a Specification class.
# The namespace is optional, you can place specification classes anywhere.
php artisan openapi:make-specification Specifications/PetsSpecification
<?php namespace App\Specifications; use LaravelOpenAPI\Specification\YamlSpecification; use LaravelOpenAPI\Specification\JsonSpecification; // The Specification class must implement YamlSpecification or JsonSpecification interface. class PetsSpecification implements YamlSpecification { public function __invoke(): string { // As long as it returns a yaml or json string, you can resolve it as needed. return file_get_contents(storage_path('openapi/pets.yml')); // Another example (JSON in this case) // return \Cache::rememberForever(self::class, fn () => \Http::get('https://petstore3.swagger.io/api/v3/openapi.json')->body()); } }
OpenAPI Requests
Once a Specification is set, You can create OpenAPI Request and define which specification it should use.
The package will handle the request validation based on the specification.
- If it does not match, it will return a "
422
validation error". - If the specification is missing, it will return a "
501
not implemented" error.
# Requests are placed on \App\Http\Requests\OpenAPI namespace
php artisan openapi:make-request PetRequest
OpenAPI Requests extend from \Illuminate\Foundation\Http\FormRequest
, so you might implement additional rules and authorization as defined on laravel docs
<?php namespace App\Http\Requests\OpenAPI; use LaravelOpenAPI\Request; class PetRequest extends Request { /** {@inheritDoc} */ public function getSpecification(): string { return \App\Specifications\PetsSpecification::class; } }
Usage
The package includes the \LaravelOpenAPI\OpenAPI
class as an accessor for all the package features.
Check this repository's laravel
folder to see the package usage on a real laravel project.
Example
This example defines a FindPetByIdController controller which uses the package to handle the request and the response.
<?php namespace App\Http\Controllers\Pet; use App\Http\Controllers\Controller; use App\Http\Requests\OpenAPI\PetRequest; use App\Http\Resources\PetResource; use App\Models\Pet; use Illuminate\Http\JsonResponse; use LaravelOpenAPI\OpenAPI; // GET /api/pet/{petId} class FindPetByIdController extends Controller { public function __invoke(PetRequest $request, int $petId): JsonResponse { if (is_null($pet = Pet::find($petId))) { OpenAPI::abort(JsonResponse::HTTP_NOT_FOUND)->forRequest($request); } return OpenAPI::response(new PetResource($pet))->forRequest($request); } }
Author
Created by Roger Vilà
License
OpenAPI Laravel is open-sourced software licensed under the MIT license.