Download the PHP package zero-to-prod/laravel-openapi without Composer

Laravel OpenAPI

Laravel OpenAPI generates an OpenAPI document to help users build confidently with your API.

The package uses the OpenAPI specification as part of the package API itself.

This is especially useful for AI agents, because many models are already trained on the OpenAPI specification. They can build with this package effectively without specialized knowledge or skills.

Requirements

• PHP ^8.5
• Laravel 13

Installation

Laravel OpenAPI can be installed via Composer:

Configuration

CLI install. It asks where the document is served, what its declared paths are relative to, and whether to validate them, then writes config/openapi.php:

Rerunning it is safe: the file reports created, unchanged or updated, and is only overwritten once you confirm. Agents can do the same through the install tool.

To publish the configuration file by itself instead:

Agent development

This project ships with an MCP server to aid in agent development.

Quick start

Annotate a controller method. Whatever you write here is placed in the document.

Use the OpenAPI specification and that your application actually behaves the way it claims.

GET /openapi.json serves:

The fragment on every registered route is merged into the document-level fields from config/openapi.php, paths are sorted, and the result is served verbatim. Nothing is rewritten or checked on the way out, so run openapi:validate before you deploy.

Paths in the attribute are resolved relative to the first entry in openapi.servers. With the default of / they are absolute, so declare the path the route actually serves.

Building a fragment at runtime

An attribute argument is a constant expression, so an array literal cannot call a function. Pass a closure instead and the fragment is built when the document is generated:

It must be written static function () { ... }. An arrow function captures by value and so is not a constant expression:

The closure runs on every request to the schema endpoint, so keep it cheap or cache what it builds.

Routing

By default, the package registers one route: GET /openapi.json, named openapi.schema.

For full customization, turn the default off and place the route:

Override the route:

Moving the endpoint does not move how it is documented: the document always describes this route as /openapi.json. Keep the two in step, or accept that the document describes the old path — openapi:validate reports the drift either way.

Validation

This package ships with optional validation tools to verify both the document and the behavior behind it.

Schema validation

This command builds the document and validates it against the OpenAPI specification.

On failure it lists the specification errors and exits non-zero; on success it exits 0, which makes it useful in a build pipeline.

Two things the specification cannot tell you are checked alongside it, and every problem is reported in the same run:

• A security requirement names a scheme; it does not $ref one, so a requirement naming a scheme no attribute declares is a valid document that fails on every request. The command names the operation instead.
• A declared path is a string, and an attribute on a route at /foo may declare /bar. The command checks each declared path against the route the attribute annotates and names both:

Declared paths resolve against the first openapi.servers URL, so with a base of /api an attribute declares /messages and not /api/messages; the error names the resolved path when a base applies. Placeholders compare by name, so {id} against {message_id} is a mismatch while the {id?} and {user:slug} a route may write are not. An attribute declaring several paths is reported only when none of them is its own route. Set openapi.validation.declared_paths to false for a document deliberately decoupled from the routes this application serves.

Behavior validation

If you want to prove the document matches your application's behavior, this package comes with built-in assertions that you can use in your tests.

Then assert against it:

The operation is resolved from the request automatically, and both the request and the response are checked. The response is returned, so the assertion can be chained onto an existing call.

Coverage

A declared response that no test ever exercises is a claim nothing checks. Every call to assertMatchesSchema() records the (path, method, status) it validated, so you can find the ones you missed.

Reset the record before the suite runs, then report on it afterwards:

The command exits non-zero while anything is missing, so it gates a build the same way openapi:validate does.

Records are appended to storage/framework/cache/openapi-coverage.jsonl, which is append-only JSON Lines so parallel test workers can share it. Change the location with openapi.coverage.path.

To assert the same thing from inside the suite, call assertSchemaFullyExercised() from a test that runs last. It only sees what the current process recorded, so prefer the command when your suite runs in parallel.

MCP server

The package registers an MCP server so coding agents can read how it is meant to be used.

Install the dependency via composer.

Set up your agents

For an agent configured by file, add the server directly:

Tools

• status — routes declaring no schema, attribute classes in use, declared responses no test reached.
• endpoint — one endpoint in full: route, middleware, attribute, declared operation, components, coverage.
• document — the merged document as served, or one top-level key.
• example — how to write and test the attribute.
• readme — this document.
• api — the exact signature of every public class, property and method.
• install — what openapi:install does, without a prompt to answer. Every argument defaults to the current setting, and a config/openapi.php that says something else is left alone and reported until the call passes overwrite: true.