PHPackages                             algirdasc/laravel-openapi-tools - 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. algirdasc/laravel-openapi-tools

ActivePackage[API Development](/categories/api)

algirdasc/laravel-openapi-tools
===============================

v0.2.1(2mo ago)22.6k↓33.3%[1 PRs](https://github.com/algirdasc/laravel-openapi-tools/pulls)GPL-3.0-or-laterPHPPHP ^8.3CI passing

Since May 10Pushed 1mo ago1 watchersCompare

[ Source](https://github.com/algirdasc/laravel-openapi-tools)[ Packagist](https://packagist.org/packages/algirdasc/laravel-openapi-tools)[ RSS](/packages/algirdasc-laravel-openapi-tools/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (13)Used By (0)

Laravel OpenAPI toolkit
=======================

[](#laravel-openapi-toolkit)

This toolkit provides rules for PHPStan and utilities for working with OpenAPI specifications in Laravel framework.

It should help you maintain documentation of your codebase more easily and lower data duplication as much as possible.

Toolkit uses [PHPStan](https://phpstan.org) to statically check code for errors, leading to Swagger/OpenAPI specification errors.

**!! Only OpenApi attributes with named arguments is supported and checked !!**

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- PHPStan
- Laravel 11.x or higher
- Composer

Installation
------------

[](#installation)

Install the package via composer:

```
composer require algirdasc/laravel-openapi-tools
```

Add rules to `phpstan.neon` config:

```
includes:
    - vendor/algirdasc/laravel-openapi-tools/extension.neon
```

Run phpstan to analyze your project:

```
vendor/bin/phpstan
```

Helper classes
--------------

[](#helper-classes)

Toolkit includes helper class to ease and minimize duplication while defining API documentation in Laravel framework. Usage of them is completely optional, although is recomended.

- [Operation Helpers](/docs/helper/operation.md)
- [Response Helpers](/docs/helper/response.md)
- [Request Body Helpers](/docs/helper/request_body.md)

Rules
-----

[](#rules)

Quick overview of rules provided in toolkit and their functions. List of incomplete and suspect for changes.

### Schemas - `OA\Schema`

[](#schemas---oaschema)

- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Schema\\PropertiesRule
    - Validates property type
    - Validates property format
    - Validates property case
    - Validates property date type & format
    - Validated property `ref` class to have schema
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Schema\\RequiredPropertiesRule
    - Validates if required properties defined in properties list
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Schema\\SchemaNameRule
    - Validates naming convention

### Operation - `OA\Get`, `OA\Post`,`OA\Put`,`OA\Patch`,`OA\Delete`

[](#operation---oaget-oapostoaputoapatchoadelete)

- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\ControllerInvokeMethodRule
    - Validates `__invoke` method has correct schema scope
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\ControllerMethodParametersRule
    - Validates if operation attributes has methods
    - Validates method parameter types
    - Validates method parameters vs. operation path parameters
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\ControllerMethodsRule
    - Validates controller method count if `__invoke` is used
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\DescriptionRule
    - Validates `description` length
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\PathRule
    - Validates path leading & trailing slash
    - Validates whether path parameters defined in operation schema parameters
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\RequestBodyReferenceRule
    - Validates whether `requestBody` is set when `FormRequest` instance provided in method parameters
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\ResponsesRule
    - Validates if `Success` response is provided
    - Validates if `Error` response is provided
    - Validates if `Authorization` response is provided
    - Validates if `Unprocessable` response is provided when `FormRequest` instance provided in method parameters
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\SummaryRule
    - Validates `summary` optimal length
- OpenApiTools\\PHPStan\\Rules\\OpenApi\\Operation\\TagCountRule
    - Validates `tags` count

### Form Request - `Illuminate\Foundation\Http\FormRequest`

[](#form-request---illuminatefoundationhttpformrequest)

- OpenApiTools\\PHPStan\\Rules\\Laravel\\FormRequest\\EnumRule
    - Validates whether `enum` parameter is set in `OA\Property`, depending on validation rules
- OpenApiTools\\PHPStan\\Rules\\Laravel\\FormRequest\\MissingSchemaPropertiesRule
    - Validates whether `properties` set
- OpenApiTools\\PHPStan\\Rules\\Laravel\\FormRequest\\MissingSchemaRule
    - Validates whether `OA\Schema` attribute is set
- OpenApiTools\\PHPStan\\Rules\\Laravel\\FormRequest\\NullableRule
    - Validates whether `nullable` parameter is set in `OA\Property`, depending on validation rules
- OpenApiTools\\PHPStan\\Rules\\Laravel\\FormRequest\\RequiredRule
    - Validates whether `required` parameter is set in `OA\Property`, depending on validation rules

### Json Resource - `Illuminate\Http\Resources\Json\JsonResource`

[](#json-resource---illuminatehttpresourcesjsonjsonresource)

- OpenApiTools\\PHPStan\\Rules\\Laravel\\Resource\\BooleanPropertyRule
    - Validates `boolean` property to match isset/haser naming convetion - `is_something`, `has_something`
- OpenApiTools\\PHPStan\\Rules\\Laravel\\Resource\\MissingReturnPropertyRule
    - Validates whether `OA\Schema` property returned in `toArray()` method (plain array return only)
- OpenApiTools\\PHPStan\\Rules\\Laravel\\Resource\\MissingSchemaPropertiesRule
    - Validates whether `OA\Schema` contains `properties` parameter (plain array return only)
- OpenApiTools\\PHPStan\\Rules\\Laravel\\Resource\\MissingSchemaPropertyRule
    - Validates whether returned property is in `OA\Schema` properties (plain array return only)

Customizations
--------------

[](#customizations)

### Ignoring rules

[](#ignoring-rules)

You can ignore a specific rule one time, all you need to do is to add a doc comment where this error happens. Example how to ignore `openApiTools.missingRequestSchemaAttribute` in a specific file:

```