Laravel OpenAPI

https://github.com/vyuldashev/laravel-openapi
Admin
Laravel OpenAPI is a package designed to automatically generate OpenAPI specifications for Laravel...
Tokens:51,712
Snippets:370
Trust Score:9
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install via Composer

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/README.md

Run this command to install the package using Composer.

```bash
composer require vyuldashev/laravel-openapi
```

--------------------------------

### ListPetsParameters example

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Example parameters factory from examples/petstore/OpenApi/Parameters/ListPetsParameters.php. Defines a query parameter named 'limit' that is optional and uses an integer schema with INT32 format.

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\Parameter;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Schema;
use Vyuldashev\LaravelOpenApi\Factories\ParametersFactory;

class ListPetsParameters extends ParametersFactory
{
    public function build(): array
    {
        return [
            Parameter::query()
                ->name('limit')
                ->description('How many items to return at one time (max 100)')
                ->required(false)
                ->schema(Schema::integer()->format(Schema::FORMAT_INT32)),
        ];
    }
}
```

--------------------------------

### ServersBuilder usage example

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-spec.md

Example usage of ServersBuilder::build with a server configuration that includes a URL, description, and variables. The variables map includes a default, description, and enum list.

```php
use Vyuldashev\LaravelOpenApi\Builders\ServersBuilder;

$servers = app(ServersBuilder::class)->build([
    [
        'url' => 'https://{env}.example.com/api',
        'description' => 'Environment',
        'variables' => [
            'env' => ['default' => 'staging', 'description' => 'Environment name', 'enum' => ['prod', 'staging', 'dev']],
        ],
    ],
]);

```

--------------------------------

### PetSchema example implementing Reusable

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Example schema factory from examples/petstore/OpenApi/Schemas/PetSchema.php. Implements Reusable to register under components/schemas. Builds an object schema with required properties id and name, and optional tag.

```php
use GoldSpecDigital\ObjectOrientedOAS\Contracts\SchemaContract;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Schema;
use Vyuldashev\LaravelOpenApi\Contracts\Reusable;
use Vyuldashev\LaravelOpenApi\Factories\SchemaFactory;

class PetSchema extends SchemaFactory implements Reusable
{
    public function build(): SchemaContract
    {
        return Schema::object('Pet')
            ->required('id', 'name')
            ->properties(
                Schema::integer('id')->format(Schema::FORMAT_INT64),
                Schema::string('name'),
                Schema::string('tag')
            );
    }
}
```

--------------------------------

### Attribute-driven PetController example

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-paths.md

Full example of a controller using OpenAPI attributes to define a path item and operation. The operationId is 'listPets', summary 'List all pets.', with a 'limit' query parameter and a 422 response referencing ErrorValidation.

```php
namespace Examples\Petstore;

use Examples\Petstore\OpenApi\Parameters\ListPetsParameters;
use Examples\Petstore\OpenApi\Responses\ErrorValidationResponse;
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class PetController
{
    /**
     * List all pets.
     */
    #[OpenApi\Operation('listPets')]
    #[OpenApi\Parameters(ListPetsParameters::class)]
    #[OpenApi\Response(ErrorValidationResponse::class, 422)]
    public function index()
    {
    }
}
```

--------------------------------

### Custom controller for a collection with route and binding

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/openapi-controller.md

Advanced setup to serve a named collection. The custom controller accepts a collection parameter, the route uses a named parameter, and the service provider binds the custom controller in place of the default. After this, GET /openapi/v1 serves the v1 collection.

```php
namespace App\OpenApi;

use GoldSpecDigital\ObjectOrientedOAS\OpenApi;
use Vyuldashev\LaravelOpenApi\Generator;

class OpenApiController
{
    public function show(Generator $generator, string $collection): OpenApi
    {
        return $generator->generate($collection);
    }
}
```

```php
// config/openapi.php
'route' => [
    'uri' => '/openapi/{collection}', // named route parameter
    'middleware' => [],
],
```

```php
// app/Providers/AppServiceProvider.php
use App\OpenApi\OpenApiController as CustomOpenApiController;
use Illuminate\Support\ServiceProvider;
use Vyuldashev\LaravelOpenApi\Http\OpenApiController;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->bind(OpenApiController::class, function ($app) {
            return $app->make(CustomOpenApiController::class);
        });
    }
}
```

--------------------------------

### UserCreateRequestBody example using RequestBodyFactory

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Example factory class that builds a request body with a description and JSON media type referencing a UserSchema. Demonstrates the required build() method implementation.

```php
use App\OpenApi\Schemas\UserSchema;
use GoldSpecDigital\ObjectOrientedOAS\Objects\MediaType;
use GoldSpecDigital\ObjectOrientedOAS\Objects\RequestBody;
use Vyuldashev\LaravelOpenApi\Factories\RequestBodyFactory;

class UserCreateRequestBody extends RequestBodyFactory
{
    public function build(): RequestBody
    {
        return RequestBody::create('UserCreate')
            ->description('User data')
            ->content(
                MediaType::json()->schema(UserSchema::ref())
            );
    }
}
```

--------------------------------

### TagsBuilder usage example

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-spec.md

Example usage of TagsBuilder::build with tag configurations. The second tag includes an externalDocs entry with description and URL.

```php
use Vyuldashev\LaravelOpenApi\Builders\TagsBuilder;

$tags = app(TagsBuilder::class)->build([
    ['name' => 'user', 'description' => 'Application users'],
    [
        'name' => 'post',
        'description' => 'Posts',
        'externalDocs' => ['description' => 'External API documentation', 'url' => 'https://example.com/external-docs'],
    ],
]);

```

--------------------------------

### openapi:make-schema usage examples

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Shows how to generate a Schema factory class. The -m option generates from the User model's columns, and --force recreates an existing class.

```bash
php artisan openapi:make-schema User
php artisan openapi:make-schema User -m User        # generate from the User model's columns
php artisan openapi:make-schema User --model User --force
```

--------------------------------

### Usage example: PetSchema implementing Reusable

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/contracts.md

Shows how to implement the Reusable interface on a SchemaFactory class. The build() method should return a SchemaContract, and the class will be registered in components/schemas.

```php
use Vyuldashev\LaravelOpenApi\Contracts\Reusable;
use Vyuldashev\LaravelOpenApi\Factories\SchemaFactory;

class PetSchema extends SchemaFactory implements Reusable
{
    // build(): SchemaContract — registered in components/schemas
}
```

--------------------------------

### BearerTokenSecurityScheme example

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Example implementation of a SecuritySchemeFactory subclass. It creates an HTTP bearer security scheme with JWT format. This class is automatically registered under components/securitySchemes.

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\SecurityScheme;
use Vyuldashev\LaravelOpenApi\Factories\SecuritySchemeFactory;

class BearerTokenSecurityScheme extends SecuritySchemeFactory
{
    public function build(): SecurityScheme
    {
        return SecurityScheme::create('BearerTokenSecurityScheme')
            ->type(SecurityScheme::TYPE_HTTP)
            ->scheme('bearer')
            ->bearerFormat('JWT');
    }
}
```

--------------------------------

### GET /openapi

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/openapi-controller.md

Serves the generated OpenAPI 3.0.2 document for the default collection. The controller's show method is invoked by the route registered in routes/api.php.

```APIDOC
## GET /openapi

### Description
Returns the generated OpenAPI document for the default collection.

### Method
GET

### Endpoint
/openapi

### Parameters
None

### Request Example
No request body or parameters required.

### Response
#### Success Response (200)
- **Content-Type**: application/json
- **Body**: The generated OpenAPI 3.0.2 document as JSON.

#### Response Example
{
  "openapi": "3.0.2",
  "info": {
    "title": "API",
    "version": "1.0.0"
  },
  "paths": {}
}

### Error Handling
Exceptions from the generator propagate to Laravel's error handler.
```

--------------------------------

### Component middleware configuration in config/openapi.php

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-components.md

Example configuration for component middlewares. The 'components' key under 'middlewares' lists middleware class names that will be applied after building the components object. This is referenced from docs/middlewares.md.

```php
// config/openapi.php
'middlewares' => [
    'paths' => [],
    'components' => [
        'App\OpenApi\Middlewares\AuditComponentsMiddleware',
    ],
],
```

--------------------------------

### Build Info object with InfoBuilder

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-spec.md

Example of building an Info object with the InfoBuilder. The config array includes title, description, version, contact, license, and extensions. The contact and license are only attached if their required fields are present.

```php
use Illuminate\Support\Arr;
use Vyuldashev\LaravelOpenApi\Builders\InfoBuilder;

$info = app(InfoBuilder::class)->build([
    'title' => 'Petstore API',
    'description' => 'Example pet store',
    'version' => '2.0.0',
    'contact' => ['name' => 'Support', 'email' => 'support@example.com'],
    'license' => ['name' => 'MIT', 'url' => 'https://opensource.org/licenses/MIT'],
    'extensions' => ['x-info-note' => 'generated'],
]);
```

--------------------------------

### AuditComponentsMiddleware implementation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/contracts.md

Example implementation of ComponentMiddleware that adds an x-generated-at extension to the Components object. Register the class name in config('openapi.collections.<collection>.middlewares.components').

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\Components;
use Vyuldashev\LaravelOpenApi\Contracts\ComponentMiddleware;

class AuditComponentsMiddleware implements ComponentMiddleware
{
    public function after(Components $components): void
    {
        $components->x('x-generated-at', date('c'));
    }
}
```

--------------------------------

### Direct discovery with custom directory set using SchemasBuilder

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-components.md

Example of instantiating SchemasBuilder with a custom directory set and calling build with a collection filter to retrieve schema objects.

```php
use Vyuldashev\LaravelOpenApi\Builders\Components\SchemasBuilder;

$builder = new SchemasBuilder([app_path('OpenApi/ExtraSchemas')]);
$schemas = $builder->build('v1'); // collection-filtered Schema objects
```

--------------------------------

### ErrorValidationResponse example using ResponseFactory

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Example factory class that builds a validation error response with a schema containing message and errors properties. Implements the Reusable interface for component registration.

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\MediaType;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Response;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Schema;
use Vyuldashev\LaravelOpenApi\Contracts\Reusable;
use Vyuldashev\LaravelOpenApi\Factories\ResponseFactory;

class ErrorValidationResponse extends ResponseFactory implements Reusable
{
    public function build(): Response
    {
        $response = Schema::object()->properties(
            Schema::string('message')->example('The given data was invalid.'),
            Schema::object('errors')
                ->additionalProperties(Schema::array()->items(Schema::string()))
                ->example(['field' => ['Something is wrong with this field!']])
        );

        return Response::create('ErrorValidation')
            ->description('Validation errors')
            ->content(MediaType::json()->schema($response));
    }
}
```

--------------------------------

### OpenAPI JSON response for /pets endpoint

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/endpoints.md

Example response from the OpenAPI endpoint, showing the structure with info, servers, paths, and components. It includes a 'Pet' schema and an 'ErrorValidation' response, mirroring the petstore fixtures.

```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "My App",
    "version": "1.0.0",
    "description": null
  },
  "servers": [ { "url": "http://localhost", "description": null, "variables": [] } ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets.",
        "operationId": "listPets",
        "parameters": [
          { "name": "limit", "in": "query", "description": "How many items to return at one time (max 100)", "required": false, "schema": { "type": "integer", "format": "int32" } }
        ],
        "responses": {
          "422": { "$ref": "#/components/responses/ErrorValidation" }
        }
      }
    }
  },
  "components": {
    "responses": { "ErrorValidation": { "description": "Validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } } },
    "schemas": { "Pet": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } } }
  }
}
```

--------------------------------

### GET /openapi

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/endpoints.md

Retrieves the OpenAPI specification document for the application. The endpoint is available at the configured URI, defaulting to '/openapi'.

```APIDOC
## GET /openapi

### Description
Retrieves the OpenAPI specification document for the application. The endpoint is available at the configured URI, defaulting to '/openapi'.

### Method
GET

### Endpoint
/openapi

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - How many items to return at one time (max 100)

### Request Example
```bash
curl http://localhost:8000/openapi
```

### Response
#### Success Response (200)
- **openapi** (string) - The OpenAPI version.
- **info** (object) - Metadata about the API.
- **servers** (array) - List of server URLs.
- **paths** (object) - Available endpoints and operations.
- **components** (object) - Reusable components.

#### Response Example
```json
{
  "openapi": "3.0.2",
  "info": {
    "title": "My App",
    "version": "1.0.0",
    "description": null
  },
  "servers": [ { "url": "http://localhost", "description": null, "variables": [] } ],
  "paths": {
    "/pets": {
      "get": {
        "summary": "List all pets.",
        "operationId": "listPets",
        "parameters": [
          { "name": "limit", "in": "query", "description": "How many items to return at one time (max 100)", "required": false, "schema": { "type": "integer", "format": "int32" } }
        ],
        "responses": {
          "422": { "$ref": "#/components/responses/ErrorValidation" }
        }
      }
    }
  },
  "components": {
    "responses": { "ErrorValidation": { "description": "Validation errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } } },
    "schemas": { "Pet": { "type": "object", "required": ["id", "name"], "properties": { "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "tag": { "type": "string" } } } }
  }
}
```
```

--------------------------------

### Handling missing docblock exception

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-operation.md

Shows how to catch the exception thrown when a route with path parameters lacks a docblock. The message starts with 'Missing docblock for route:'.

```php
use Illuminate\Routing\Route;
use Vyuldashev\LaravelOpenApi\Builders\Paths\Operation\ParametersBuilder;
use Vyuldashev\LaravelOpenApi\RouteInformation;

$route = RouteInformation::createFromRoute($someRoute);
try {
    $params = app(ParametersBuilder::class)->build($route);
} catch (\Exception $e) {
    if (Str::startsWith($e->getMessage(), 'Missing docblock for route:')) {
        // add a docblock to the controller action
    }
}
```

--------------------------------

### Route registration logic in routes/api.php

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/endpoints.md

Registers a GET route for each configured collection, reading the URI and middleware from the collection's config. Skips registration if the URI is falsy (e.g., null). Route name is 'openapi.<name>.specification'.

```php
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Route;
use Vyuldashev\LaravelOpenApi\Http\OpenApiController;

Route::group(['as' => 'openapi.'], function () {
    foreach (config('openapi.collections', []) as $name => $config) {
        $uri = Arr::get($config, 'route.uri');

        if (! $uri) {
            continue;
        }

        Route::get($uri, [OpenApiController::class, 'show'])
            ->name($name.'.specification')
            ->middleware(Arr::get($config, 'route.middleware'));
    }
});
```

--------------------------------

### Using ExtensionsBuilder to attach vendor extensions

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-spec.md

Direct usage example: instantiate the ExtensionsBuilder via the container and call build() on an Operation object with a collection of Extension attributes. The builder filters for Extension attributes and applies their key/value pairs to the object.

```php
use Vyuldashev\LaravelOpenApi\Builders\ExtensionsBuilder;

$operation = Operation::get();
$attributes = collect([/* Extension attributes... */]);

app(ExtensionsBuilder::class)->build($operation, $attributes);
```

--------------------------------

### CallbackFactory usage example from callback.stub

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Shows a concrete implementation of CallbackFactory. The build() method returns a PathItem with a route and operations, including a request body and response. The class must implement Reusable to be registered as a component callback.

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\PathItem;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Operation;
use GoldSpecDigital\ObjectOrientedOAS\Objects\RequestBody;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Response;
use GoldSpecDigital\ObjectOrientedOAS\Objects\MediaType;
use GoldSpecDigital\ObjectOrientedOAS\Objects\Schema;
use Vyuldashev\LaravelOpenApi\Factories\CallbackFactory;

class MyEventCallback extends CallbackFactory
{
    public function build(): PathItem
    {
        return PathItem::create('MyEvent')
            ->route('{$request.body#/callbackUrl}')
            ->operations(
                Operation::post()
                    ->requestBody(
                        RequestBody::create()
                            ->description('something happened')
                            ->content(
                                MediaType::json()->schema(Schema::object()->properties(Schema::string('foo')))
                            )
                    )
                    ->responses(
                        Response::ok()->description('Your server returns this code if it accepts the callback')
                    )
            );
    }
}
```

--------------------------------

### AuditPathMiddleware implementation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/contracts.md

Example implementation of PathMiddleware. The before method drops all action attributes for routes with URI '/internal', causing them to be excluded later. The after method decorates every path item with an 'x-audited' extension.

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\PathItem;
use Vyuldashev\LaravelOpenApi\Contracts\PathMiddleware;
use Vyuldashev\LaravelOpenApi\RouteInformation;

class AuditPathMiddleware implements PathMiddleware
{
    public function before(RouteInformation $routeInformation): void
    {
        if ($routeInformation->uri === '/internal') {
            $routeInformation->actionAttributes = collect([]); // drop all attributes -> excluded later
        }
    }

    public function after(PathItem $pathItem): PathItem
    {
        return $pathItem->x('x-audited', true); // decorate every path item
    }
}
```

--------------------------------

### GET /openapi/{collection}

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/openapi-controller.md

Serves the generated OpenAPI document for a named collection. This requires a custom controller that accepts a collection parameter and a custom route with a named parameter.

```APIDOC
## GET /openapi/{collection}

### Description
Returns the generated OpenAPI document for the specified collection.

### Method
GET

### Endpoint
/openapi/{collection}

### Parameters
#### Path Parameters
- **collection** (string) - Required - The name of the collection to generate.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **Content-Type**: application/json
- **Body**: The generated OpenAPI 3.0.2 document for the specified collection as JSON.

#### Response Example
{
  "openapi": "3.0.2",
  "info": {
    "title": "API",
    "version": "1.0.0"
  },
  "paths": {}
}

### Error Handling
Exceptions from the generator propagate to Laravel's error handler.
```

--------------------------------

### Usage of Parameters attribute in a controller

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/attributes-object-factories.md

Shows how to apply the Parameters attribute to a controller method. The attribute references a factory class that builds the OpenAPI parameters. The example uses the OpenApi\PathItem and OpenApi\Operation attributes.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * List users.
     */
    #[OpenApi\Operation]
    #[OpenApi\Parameters(ListUsersParameters::class)]
    public function index()
    {
        // ...
    }
}
```

--------------------------------

### Using #[OpenApi\Parameters] attribute

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-operation.md

Example controller using the Parameters attribute to define operation parameters. The docblock @param tag provides descriptions for path parameters.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * List users.
     *
     * @param  int  $withTrashed  Display trashed users too   // docblock gives path-param descriptions
     */
    #[OpenApi\Operation]
    #[OpenApi\Parameters(ListUsersParameters::class)]
    public function index()
    {
        // ...
    }
}
```

--------------------------------

### RequestBody usage example

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/attributes-object-factories.md

Shows how to apply the RequestBody attribute to a controller method. The factory class name is resolved relative to the App\OpenApi\RequestBodies namespace if not fully qualified.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * Create a user.
     */
    #[OpenApi\Operation(tags: ['user'])]
    #[OpenApi\RequestBody(UserCreateRequestBody::class)]
    public function store(Request $request)
    {
        // ...
    }
}
```

--------------------------------

### Error handling at declaration time

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/attributes-path-item-collection-operation.md

Shows how a mistyped security class throws an InvalidArgumentException when the attribute is instantiated. The example catches the exception and logs the message.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

try {
    $attribute = new #[OpenApi\Operation('x', security: 'NonExistentScheme')];
} catch (InvalidArgumentException $e) {
    // "Security class is either not declared or is not an instance of ..."
    log_error($e->getMessage());
}
```

--------------------------------

### Fetch OpenAPI specification with curl

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/endpoints.md

Sends a GET request to the default endpoint URI '/openapi' on the local server. The response is the OpenAPI 3.0.2 JSON document for the application.

```bash
curl http://localhost:8000/openapi
```

--------------------------------

### Usage: SchemaHelpers::guessFromReflectionType for an int parameter

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/class-map-generator.md

Demonstrates how to use guessFromReflectionType to convert a reflected type to an OAS schema. In this example, an 'int' parameter type results in Schema::integer()

```php
use Vyuldashev\LaravelOpenApi\SchemaHelpers;

$type = /* ReflectionNamedType for an 'int' parameter */;
$schema = SchemaHelpers::guessFromReflectionType($type); // Schema::integer()
```

--------------------------------

### Configure security requirements with SecurityRequirement::create()

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/configuration.md

Sets a list of security requirement objects for the collection. The example uses `GoldSpecDigital\ObjectOrientedOAS\Objects\SecurityRequirement::create()->securityScheme('BearerToken')` to define a Bearer token scheme. This is applied document-wide via `OpenApi::security(...)` in `Generator::generate`.

```php
'security' => [
    GoldSpecDigital\ObjectOrientedOAS\Objects\SecurityRequirement::create()->securityScheme('BearerToken'),
],
```

--------------------------------

### GET {uri}

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/endpoints.md

Serves the generated OpenAPI 3.0.2 specification document as JSON for a given collection. The URI is configured per collection via 'route.uri' (default '/openapi'), and the response is the full OpenAPI document generated by the Generator.

```APIDOC
## GET {uri}

### Description
Serves the generated OpenAPI 3.0.2 specification document as JSON for a given collection. The URI is configured per collection via 'route.uri' (default '/openapi'), and the response is the full OpenAPI document generated by the Generator.

### Method
GET

### Endpoint
{uri} — where {uri} is the value of config('openapi.collections.<name>.route.uri'), default '/openapi' for the 'default' collection.

### Parameters
#### Path Parameters
- **{collection}** (string) - Optional - Only present if you override the controller and configure 'uri' => '/openapi/{collection}'. This path parameter is forwarded to the custom show(Generator $generator, string $collection) action. Not wired by the package itself; the route simply forwards any path parameters to the bound controller action.

#### Query Parameters
- None

#### Request Body
- None (GET request)

### Request Example
(No request body or query parameters)

### Response
#### Success Response (200)
- **openapi** (string) - The OpenAPI version constant '3.0.2'.
- **info** (object) - From InfoBuilder, sourced from config 'info'.
- **servers** (array) - From ServersBuilder, sourced from config 'servers'.
- **paths** (object) - From PathsBuilder, built from annotated routes.
- **components** (object, optional) - From ComponentsBuilder, omitted when there are no reusable objects.
- **security** (array) - From config 'security'.
- **tags** (array) - From TagsBuilder, sourced from config 'tags'.
- **x-* extensions** (mixed) - From config 'extensions'.

#### Response Example
{
  "openapi": "3.0.2",
  "info": {},
  "servers": [],
  "paths": {},
  "components": {},
  "security": [],
  "tags": []
}

#### Error Response (500)
- Generation failed — exceptions from the generator/builders propagate to Laravel's error handler.

### Authentication
None built in; arbitrary middleware may be attached via the collection's 'route.middleware' config array.

### Route Registration
- Route name: openapi.<name>.specification
- Middleware: config('openapi.collections.<name>.route.middleware') (default [])
- Registration: Route is registered only if the URI is truthy; a falsy URI (e.g., null) skips registration entirely.
```

--------------------------------

### Define vendor extensions with x-tagGroups

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/configuration.md

Maps vendor extension keys to values, applied to the document root via `$openApi->x($key, $value)`. The example defines an `x-tagGroups` extension with a tag group named 'General' containing the 'user' tag.

```php
'extensions' => [
    'x-tagGroups' => [
        ['name' => 'General', 'tags' => ['user']],
    ],
],
```

--------------------------------

### CLI command to generate collection spec

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/collections.md

Run the openapi:generate command with an optional collection name. The default is 'default'. This example generates the spec for a collection named 'v1' if it exists in the config.

```bash
php artisan openapi:generate v1
```

--------------------------------

### Custom ServerFactory implementation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Shows how to implement a custom ServerFactory by extending the abstract class and returning a Server with a URL and description. The build() method must return a GoldSpecDigital\ObjectOrientedOAS\Objects\Server instance.

```php
use GoldSpecDigital\ObjectOrientedOAS\Objects\Server;
use Vyuldashev\LaravelOpenApi\Factories\ServerFactory;

class InternalServerFactory extends ServerFactory
{
    public function build(): Server
    {
        return Server::create()->url('https://internal.example.com')->description('Internal API');
    }
}
```

--------------------------------

### Map a route with RouteInformation::createFromRoute

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/route-information.md

Iterates over all registered routes and prints method, URI, controller, and action for each route. Use this to inspect route information generated by the package.

```php
use Illuminate\Routing\Router;
use Vyuldashev\LaravelOpenApi\RouteInformation;

foreach (app(Router::class)->getRoutes() as $route) {
    $info = RouteInformation::createFromRoute($route);

    printf('%s %s -> %s@%s', $info->method, $info->uri, $info->controller, $info->action);
}
```

--------------------------------

### boot method signature

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/open-api-service-provider.md

Public method that publishes the config under the 'openapi-config' tag when running in console and loads the specification routes from routes/api.php.

```php
public function boot(): void
```

--------------------------------

### CallbacksBuilder usage with Callback attribute

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-operation.md

Example usage of the CallbacksBuilder with a controller method annotated with #[OpenApi\Callback] to register a callback URL.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class WebhookController extends Controller
{
    /**
     * Register a callback URL.
     */
    #[OpenApi\Operation]
    #[OpenApi\Callback(MyEventCallback::class)]
    public function store(Request $request)
    {
        // ...
    }
}
```

--------------------------------

### Configure tags in config/openapi.php

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/operations.md

Sets up tags for logical grouping of operations. Each tag can have a name, description, and optional externalDocs link.

```php
    'tags' => [

        [
           'name' => 'post',
           'description' => 'Posts',
        ],

        [
           'name' => 'user',
           'description' => 'Application users',

           // You may optionally add a link to external documentation like so:
           'externalDocs' => [
                'description' => 'External API documentation',
                'url' => 'https://example.com/external-docs',
            ],
        ],

    ],
```

--------------------------------

### SecurityBuilder usage with security option

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-operation.md

Example usage of the SecurityBuilder with a controller method annotated with #[OpenApi\Operation(security: 'BearerTokenSecurityScheme')] to specify a security scheme.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * Create new user.
     *
     * Creates new user or returns already existing user by email.
     */
    #[OpenApi\Operation(security: 'BearerTokenSecurityScheme')]
    public function store(Request $request)
    {
        //
    }
}
```

--------------------------------

### Usage with security and method override

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/attributes-path-item-collection-operation.md

Demonstrates using the security parameter to reference a security scheme class and the method parameter to override the HTTP verb. Also shows how to disable security with an empty string.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * Update user.
     */
    // 'BearerTokenSecurityScheme' resolves to App\OpenApi\SecuritySchemes\BearerTokenSecurityScheme
    #[OpenApi\Operation(tags: ['user'], security: 'BearerTokenSecurityScheme', method: 'PATCH')]
    public function update(Request $request)
    {
        // ...
    }

    /**
     * Publicly accessible action: turns operation-level security off.
     */
    #[OpenApi\Operation(security: '')]
    public function show(Request $request)
    {
        // ...
    }
}
```

--------------------------------

### Usage: Custom class discovery with ClassMapGenerator::createMap

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/class-map-generator.md

Shows how to use createMap to scan a directory and iterate over the resulting class map, printing the class name and file path.

```php
use Vyuldashev\LaravelOpenApi\ClassMapGenerator;

$map = ClassMapGenerator::createMap(app_path('OpenApi/LegacySchemas'));

foreach ($map as $class => $path) {
    printf('%s defined in %s', $class, $path);
}
```

--------------------------------

### openapi:make-extension usage with output

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Generates an Extension factory class. The command output shows the generated class and its key() method result.

```bash
php artisan openapi:make-extension CustomHeader
# Generates App\OpenApi\Extensions\CustomHeaderExtension with key() -> 'x-custom-header'
```

--------------------------------

### openapi:make-schema command options

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Defines the command name, description, type, and options for the SchemaFactoryMakeCommand. The --model option specifies the model class schema being generated for, and --force recreates an existing class.

```php
protected $name = 'openapi:make-schema';
protected $description = 'Create a new Schema factory class';
protected $type = 'Schema';

protected function getOptions(): array
{
    return [
        ['model', 'm', InputOption::VALUE_OPTIONAL, 'The model class schema being generated for'],
        ['force', null, InputOption::VALUE_NONE, 'Create the class even if the factory already exists'],
    ];
}
```

--------------------------------

### Generate OpenAPI Documentation with php artisan openapi:generate

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/open-api-service-provider.md

Run this command to validate the service provider's configuration and generate OpenAPI documentation. Missing config values result in empty sections or default values, and missing collections print an error message.

```bash
php artisan openapi:generate
```

--------------------------------

### Define Response Factory Class

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

Extend `ResponseFactory` and implement the `build()` method to return a `Response` object. Use `Response::ok()` for a successful response and chain `description()` to set the response description.

```php
class ListUsersResponse extends ResponseFactory
{
    public function build(): Response
    {
        return Response::ok()->description('Successful response');
    }
}
```

--------------------------------

### Generate Parameters factory with Artisan

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

Creates a new ParametersFactory class via the openapi:make-parameters command.

```bash
php artisan openapi:make-parameters ListUsers
```

--------------------------------

### Manual registration and overriding a builder

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/open-api-service-provider.md

Shows how to manually register the OpenApiServiceProvider in config/app.php and then override the HTTP controller and a spec-section builder in AppServiceProvider. The controller replacement affects routes/api.php, and the builder replacement swaps the default InfoBuilder with a custom one.

```php
// config/app.php
'providers' => [
    Vyuldashev\LaravelOpenApi\OpenApiServiceProvider::class,
    App\Providers\AppServiceProvider::class,
],
```

```php
// app/Providers/AppServiceProvider.php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register()
    {
        // Replace the HTTP controller used by routes/api.php (see generator.md / collections.md)
        $this->app->bind(Vyuldashev\LaravelOpenApi\Http\OpenApiController::class, function ($app) {
            return $app->make(App\OpenApi\OpenApiController::class);
        });

        // Replace a spec-section builder
        $this->app->bind(Vyuldashev\LaravelOpenApi\Builders\InfoBuilder::class, function ($app) {
            return $app->make(App\OpenApi\CustomInfoBuilder::class);
        });
    }
}
```

--------------------------------

### Generate schema from model with -m option

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/schemas.md

Creates a schema for the User model by passing the model name with the --model or -m option. Both the schema name and model name are User.

```bash
php artisan openapi:make-schema User -m User
```

--------------------------------

### Error handling for OAS validation exception

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-paths.md

Catch the OAS validation exception around a generation run. The example catches InvalidArgumentException from the OAS library and reports it, e.g., for an invalid method override on an Operation attribute.

```php
use GoldSpecDigital\ObjectOrientedOAS\Exceptions\InvalidArgumentException;
use Vyuldashev\LaravelOpenApi\Generator;

try {
    $generator->generate();
} catch (InvalidArgumentException $e) {
    // e.g. an invalid method override on an Operation attribute
    report($e);
}
```

--------------------------------

### Create Reusable Validation Error Response

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/responses.md

Implement the `Reusable` contract to make the response reusable. The response is added to `components/responses` and referenced instead of inlined. This example defines a validation error response with a message and errors object.

```php
use Vyuldashev\LaravelOpenApi\Contracts\Reusable;

class ErrorValidationResponse extends ResponseFactory implements Reusable
{
    public function build(): Response
    {
        $response = Schema::object()->properties(
            Schema::string('message')->example('The given data was invalid.'),
            Schema::object('errors')
                ->additionalProperties(
                    Schema::array()->items(Schema::string())
                )
                ->example(['field' => ['Something is wrong with this field!']])
        );

        return Response::create('ErrorValidation')
            ->description('Validation errors')
            ->content(
                MediaType::json()->schema($response)
            );
    }
}
```

--------------------------------

### openapi:generate with named collection and file output

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Shows how to specify a named collection and write the output to a file. The --output option writes JSON to the given file instead of stdout.

```bash
php artisan openapi:generate v1
php artisan openapi:generate --output=storage/openapi.json
php artisan openapi:generate v1 --output=storage/v1.json
```

--------------------------------

### openapi:make-response usage

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Generates a Response factory class with the specified name.

```bash
php artisan openapi:make-response ListUsers
```

--------------------------------

### openapi:make-callback usage

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Generates a Callback factory class with the specified name.

```bash
php artisan openapi:make-callback MyEvent
```

--------------------------------

### Generate Request Body with Artisan Command

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/request-bodies.md

Run this command to generate a new request body class. The command creates a file in the default location for request bodies.

```bash
php artisan openapi:make-requestbody StoreUser
```

--------------------------------

### Using ServerFactory with Operation attribute

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/factories.md

Demonstrates how to attach a custom server factory to an operation using the #[OpenApi\Operation] attribute with the 'servers' parameter. The factory class is referenced by its class name, and the operation is defined within a controller method.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

#[OpenApi\PathItem]
class UserController extends Controller
{
    /**
     * List users.
     */
    #[OpenApi\Operation(servers: [InternalServerFactory::class])]
    public function index()
    {
        // ...
    }
}
```

--------------------------------

### Directly check attribute constructor validation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/errors.md

Directly instantiates an attribute to check its constructor validation. The example uses #[OpenApi\Response('NotAResponseFactory')] and catches InvalidArgumentException with the message 'Factory class must be instance of ResponseFactory'. Note that in application code you normally only add the attribute to a controller and catch around generation instead.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

try {
    new #[OpenApi\Response('NotAResponseFactory')];
} catch (InvalidArgumentException $e) {
    // 'Factory class must be instance of ResponseFactory'
}
```

--------------------------------

### Catch attribute validation errors during generation

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/errors.md

Catches attribute validation errors thrown during generation. The try block calls Generator::generate() and the catch blocks handle InvalidArgumentException (items 1-7, 11), OasInvalidArgumentException (item 9), ReflectionException (item 10), and a generic \Exception for item 8. The generic catch checks if the message starts with 'Missing docblock' to identify the specific error.

```php
use GoldSpecDigital\ObjectOrientedOAS\Exceptions\InvalidArgumentException as OasInvalidArgumentException;
use InvalidArgumentException;
use phpDocumentor\Reflection\ReflectionException;
use Vyuldashev\LaravelOpenApi\Generator;

try {
    $spec = app(Generator::class)->generate();
} catch (InvalidArgumentException $e) {
    // items 1-7, 11 — e.g. "Factory class must be instance of ParametersFactory"
    // Fix: point the attribute at the right factory base / implement Reusable
    report_config_error($e->getMessage());
} catch (OasInvalidArgumentException $e) {
    // item 9 — invalid operation assembly (e.g. bad method override)
} catch (ReflectionException $e) {
    // item 10 — controller class or action unresolvable
} catch (\Exception $e) {
    // item 8 — "Missing docblock for route: ..."
    if (Str::startsWith($e->getMessage(), 'Missing docblock')) {
        // add a docblock to the offending controller action
    }
}
```

--------------------------------

### PathMiddleware interface with before and after methods

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/contracts.md

Defines the contract for path middleware. The before method runs after all RouteInformation objects are collected and may mutate them (e.g., filter or modify actionAttributes). The after method runs after a PathItem is built for a URI and must return the possibly modified or replaced path item.

```php
interface PathMiddleware
{
    public function before(RouteInformation $routeInformation): void;

    public function after(PathItem $pathItem): PathItem;
}
```

--------------------------------

### getPathsFromConfig method signature

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/open-api-service-provider.md

Private method that takes a config key type and returns an array of unique directory paths. Reads config('openapi.locations.'.$type, []), runs each entry through glob with GLOB_ONLYDIR, then flattens and de-duplicates.

```php
private function getPathsFromConfig(string $type): array
```

--------------------------------

### Add Parameters attribute to controller

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/paths/parameters.md

Shows how to attach the Parameters attribute to a controller method, referencing the factory class.

```php
use Vyuldashev\LaravelOpenApi\Attributes as OpenApi;

class UserController extends Controller 
{
    /**
     * List users.
     */
    #[OpenApi\Operation]
    #[OpenApi\Parameters(factory: ListUsersParameters::class)]
    public function index() 
    {
        //
    }
}
```

--------------------------------

### openapi:make-security-scheme usage

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

Generates a SecurityScheme factory class with the specified name.

```bash
php artisan openapi:make-security-scheme BearerToken
```

--------------------------------

### OpenApiServiceProvider register method signature

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/open-api-service-provider.md

Declares the register method that is called during application boot.

```php
public function register(): void
```

--------------------------------

### Generator constructor

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/generator.md

Constructor signature with parameters for configuration and builders. Intended to be constructed by the container, which binds it as a singleton with all builders resolved.

```php
public function __construct(
    array $config,
    InfoBuilder $infoBuilder,
    ServersBuilder $serversBuilder,
    TagsBuilder $tagsBuilder,
    PathsBuilder $pathsBuilder,
    ComponentsBuilder $componentsBuilder
)
```

--------------------------------

### Define openapi:routes command in RoutesCommand class

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/console-commands.md

The RoutesCommand class defines the openapi:routes command with a signature and description. Its handle method is empty in the source, but the command delegates to the built-in route:list via $this->call('route:list'). This command is not registered by OpenApiServiceProvider in the current source.

```php
class RoutesCommand extends Command
{
    protected $signature = 'openapi:routes';
    protected $description = 'List all registered route with additional information';

    public function handle(): void
}
```

--------------------------------

### Manually register service provider

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/README.md

Add this provider to the 'providers' array in config/app.php if automatic registration is not used.

```php
'providers' => [
    // ...
    Vyuldashev\LaravelOpenApi\OpenApiServiceProvider::class,
];
```

--------------------------------

### Generate schema with artisan command

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/docs/schemas.md

Creates a new OpenAPI schema class named User. Run in the project root.

```bash
php artisan openapi:make-schema User
```

--------------------------------

### Publish OpenAPI config with artisan vendor:publish

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/open-api-service-provider.md

Publishes the package's configuration file using the provider and tag 'openapi-config'.

```bash
php artisan vendor:publish --provider="Vyuldashev\LaravelOpenApi\OpenApiServiceProvider" --tag="openapi-config"
```

--------------------------------

### ParametersBuilder class skeleton

Source: https://github.com/vyuldashev/laravel-openapi/blob/master/_autodocs/api-reference/builders-operation.md

Shows the public and protected method signatures of ParametersBuilder. The build method returns an array of Parameter objects by merging path and attribute parameters.

```php
class ParametersBuilder
{
    public function build(RouteInformation $route): array

    protected function buildPath(RouteInformation $route): Collection

    protected function buildAttribute(RouteInformation $route): Collection
}
```
Tokens:
Raw