OpenAPI Specs
A frontend team, an API design tool or a partner often hands you an OpenAPI document before any backend exists. Generate the Laravel side of it in one command, from OpenAPI 3.0, 3.1 or Swagger 2.0, in JSON or YAML.
Usage
php artisan make:fullapi --openapi=openapi.yaml --dry-runphp artisan make:fullapi --openapi=openapi.yamlcurl -s https://example.com/openapi.json | php artisan make:fullapi --openapi=- --dry-runEvery other option works as with a schema file, including --json, --auth, --postman, --pest and --query-builder.
What becomes what
Each object schema of components.schemas (or definitions in Swagger 2.0) becomes an entity, and its properties become columns.
| In the spec | In the generated API |
|---|---|
integer (int64: bigint), number (float, double: float, otherwise decimal), boolean | the matching column |
string with date, date-time, time or uuid format | a date, datetime, time or uuid field |
string with maxLength above 255 | text |
string with enum | a PHP enum class, cast on the model and validated |
array or object without a reference | json |
A property absent from required, nullable: true or type: [x, "null"] | a nullable column |
default | the column default |
author: { $ref: User } | author relation (belongsTo) and its author_id column |
posts: { type: array, items: { $ref: Post } } | hasMany, or belongsToMany when both schemas list each other |
post_id or postId next to a Post schema | a belongsTo relation instead of a plain integer |
deleted_at or deletedAt | soft deletes |
id of type string | a custom primary key (uuid with the uuid format) |
id, created_at and updated_at, in snake case or camel case, are left to the generator. Properties defined through allOf are merged, and a reference wrapped in allOf, oneOf or anyOf, the OpenAPI 3.0 way to make it nullable, still counts as a relation.
Schemas left aside
A spec also describes payloads that are not resources. These schemas are skipped, and each one is named in an openapi_schema_skipped warning:
- errors and pagination:
Error,ErrorResponse,ValidationError,ProblemDetails,Pagination,Meta,Links; - variants of another schema, such as
NewPet,CreatePetRequest,UpdatePetInput,PetResponseorPetListnext to aPetschema; - object schemas without properties.
A LeaveRequest or a LandingPage stays a resource, since no Leave or Landing schema exists next to it. String enums declared as their own schema, such as OrderStatus, become the type of the properties that reference them.
Read the warnings of the dry run before generating, and rename or remove a schema in the spec when the guess is wrong.
With an agent
The MCP server takes the same input: plan-api and generate-api accept the path of a spec in the project instead of an api-schema document, so an agent can generate from docs/openapi.yaml without copying it into the conversation.