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.

rogervila / openapi-laravel

Maintainers

Details