Download the PHP package nicoandra/laravel-data-openapi-generator without Composer

Laravel Data OpenAPI Generator

Generate an OpenAPI specification directly from Laravel routes and Spatie Laravel Data classes.

The package treats your controllers and Data objects as the source of truth for request and response documentation, so your OpenAPI file stays close to the code that actually handles the API.

What it does

• Generates OpenAPI paths from Laravel routes.
• Infers request bodies and response schemas from Data classes.
• Supports route parameters declared directly in controller methods.
• Supports route parameters injected through #[FromRouteParameter(...)].
• Reads #[Summary], #[Description], and #[Example] attributes to enrich the generated spec.
• Supports #[IgnoreFromOpenApi] on request properties, controller classes, and controller methods, to keep utility methods from being exposed to the public.
• Supports custom response status codes through #[HttpResponseStatus(...)].
• Supports multiple content types through #[CustomContentType(...)].
• Supports documenting transformed or cast Data values as OpenAPI scalar types through #[ExposedAs(...)] without changing runtime casting.
• Adds security requirements and 401 / 403 responses from configured middleware.
• Allows namespace aliasing so generated schema names do not leak internal class structure.
• Exposes both a JSON endpoint and a Swagger UI page.

Installation

Install the package:

Publish the configuration:

Quick start

Use Data classes for your API inputs and outputs:

Annotate the controller method:

Register a route:

Generate the OpenAPI file:

By default the generated file is written to resources/api/openapi.json.

Generated routes

The package registers two routes:

• GET /api/openapi renders Swagger UI.
• GET /api/openapi.json returns the generated OpenAPI JSON.

Generate the file first with:

Supported attributes

#[Summary(...)]

Attach to a controller method to populate the OpenAPI operation summary.

#[Description(...)]

Attach to a controller method to describe the operation.

Attach to a Data class to describe the response associated with that class.

#[Example(...)]

Attach to a Data property or controller parameter to add example values to the generated schema or parameter.

#[IgnoreFromOpenApi]

Attach to a request Data property to exclude it from generated request bodies and derived GET query parameters.

Attach to a controller class or controller method to exclude matching routes from the generated OpenAPI document.

#[HttpResponseStatus(...)]

Attach to a response Data class to change the generated HTTP status code for that response.

#[CustomContentType(...)]

Attach to a Data class to emit request and response content under one or more custom content types.

#[ExposedAs(...)]

Use #[ExposedAs('string')] to document a transformed or cast value as an OpenAPI string. The constructor currently accepts only the literal value 'string'; the attribute changes the generated OpenAPI representation, not runtime casting or transformation behavior.

At class level, apply it to a Data class whose generated schema should be a string instead of an object reference:

At property level, apply it when a property typed as a transformed or cast Data value is exposed as a string in the schema:

Although the PHP attribute declaration permits class, property, and parameter targets, documented and generated support currently covers Data classes and Data properties only. Controller-parameter handling is not currently implemented. In the supported cases, it affects only the generated OpenAPI schema; it does not cast, transform, or otherwise change the runtime value.

#[Tags(...)]

Attach to a controller class or method to add OpenAPI tags to the generated operation.

Configuration

The published config file lives at config/openapi-generator.php.

Important options:

• openapi: OpenAPI version to generate. Default: 3.0.2
• version: API version shown in the document. Default: 1.0.0
• name: API title shown in the document. Default: OpenAPI
• path: output path for the generated JSON file
• included_route_prefixes: only routes with these URI prefixes are documented
• ignored_route_names: route names to exclude
• ignored_methods: HTTP methods to skip, such as HEAD and OPTIONS
• security_middlewares: middleware-to-security-scheme mapping
• overlay_files: optional OpenAPI JSON files to add manual documentation gaps
• namespace_aliases: alias internal namespaces in generated schema names
• error_scheme_class: Data class used for generated error responses

Example namespace aliasing:

This keeps schema names stable and avoids exposing internal namespace structure in your OpenAPI document.

Overlay spec files

Use overlay_files when you need manual additions that cannot be inferred from Laravel routes or Data classes, such as legacy endpoints, custom headers, or extra response variants.

Overlay specs are additive. They can add:

• New paths.
• New methods under existing paths.
• New responses by status code under an existing paths.{route}.{method} operation.
• New components.schemas entries.
• New components.securitySchemes entries.

The generated spec is authoritative. If the generated file already has a path, method, response status code, schema, or security scheme with the same key, that generated value is kept and the overlay value is ignored for that key. For example, if both generated output and the overlay define GET /api/users response 200, the generated 200 response wins; the overlay can still add 404 or other missing status codes.

Security integration

Routes using configured auth middleware are emitted with OpenAPI security requirements.

If a route includes authorization middleware such as can:update-posts, the generated operation description also includes the required permissions and the package adds 403 Forbidden responses alongside 401 Unauthorized where appropriate.

Notes and limitations

• Request and response inference is built around Spatie\LaravelData\Data.
• Array and DataCollection responses should have precise return docblocks so item types can be resolved.
• GET endpoints do not emit a request body. If a Data object is used there, its properties are converted into query parameters.

Optional frontend integration

If you use vite-plugin-pwa, exclude /api/ routes from the service worker:

Minimal Vue page:

Development

You can also start the container with make dev and run commands from there.

For test coverage, run `make test-coverage``