Learn.openapis.org Laravel Package

Getting Started

oai/learn.openapis.org is not a Composer package — it is the source repository for the OpenAPI Initiative's learning site (learn.openapis.org), licensed CC-BY-4.0. Treat it as a specification reference and design guide, not a dependency. There is nothing to composer require, no service provider, no config file to publish.

Minimal steps

1. Read it at https://learn.openapis.org (or clone the repo and serve the Markdown/MDX locally if you want an offline copy in your team wiki).
2. Bookmark two sections you will return to constantly:
   • Basic Structure — the root object (openapi, info, paths, components).
   • Describing Responses / Describing Request Body — where most Laravel developers get stuck first.
3. Decide your OpenAPI minor version up front: 3.0.x (broadest tooling support) vs 3.1.x (JSON Schema 2020-12, nullable removed, examples array semantics). The site documents both; do not mix them in one file.
4. Create your first artefact: openapi.yaml at the repo root, checked into Git next to the Laravel app.

First use case

Document one real endpoint from your Laravel app — say POST /api/v1/orders — using the site's "Basic Structure" as the skeleton, then wire it into a docs route:

// routes/web.php
Route::get('/docs', fn () => view('docs')); // Redoc / Swagger UI shell

// A raw spec endpoint the UI can fetch
Route::get('/openapi.yaml', fn () => response()->file(base_path('openapi.yaml'), [
    'Content-Type' => 'application/yaml',
]));

From day one, put a linter in the loop so the spec cannot drift into invalidity:

npx @redocly/cli lint openapi.yaml
# or
npx @stoplight/spectral-cli lint openapi.yaml

Implementation Patterns

1. Contract-first for public/partner APIs

For anything external, write the spec before the controller. The learn.openapis.org "Reusing Descriptions" and "Components" sections are the reference for extracting schemas, parameters, responses, and securitySchemes into components so they are $ref-able. This lets you:

• Generate TypeScript clients for a frontend (orval, openapi-generator).
• Generate a Postman/Bruno collection for QA.
• Diff breaking changes in CI with oasdiff or openapi-diff.

2. Code-first with Scramble, spec as the artefact

For internal Laravel APIs the pragmatic path is dedoc/scramble, which derives an OpenAPI document from your routes, FormRequests, API Resources, and PHPDoc. Then use learn.openapis.org to correct the generated output (accurate response envelopes, securitySchemes, error schemas) rather than hand-writing everything.

composer require dedoc/scramble --dev
php artisan vendor:publish --provider="Dedoc\Scramble\ScrambleServiceProvider"
php artisan scramble:export --path=openapi.yaml

Once openapi.yaml is a build artefact, it becomes your contract: lint it, diff it, publish it.

3. Serving interactive docs inside Laravel

Two common shapes:

• Swagger UI via l5-swagger (works well when the spec is generated by zircote/swagger-php annotations).
• Redoc as a single blade view — lighter and nicer for read-only docs:

{{-- resources/views/docs.blade.php --}}
<redoc spec-url="{{ url('/openapi.yaml') }}"></redoc>
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>

4. Request/response validation driven by the spec

Use the spec as the source of truth for validation in tests, not just docs. league/openapi-psr7-validator or osteel/openapi-httpfoundation-testing in PHPUnit asserts that real Laravel responses still satisfy the documented schema:

$this->assertResponseMatchesOpenApiSchema(
    $this->getJson('/api/v1/orders'),
    base_path('openapi.yaml')
);

This is the single highest-value pattern: it turns the docs into executable contract tests and catches drift the moment a Resource changes shape.

5. Security scheme documentation matching Sanctum/Passport

Document what you actually ship. Sanctum SPA cookie auth is not bearerAuth — it is apiKey in cookie with XSRF-TOKEN, plus a CSRF note. Token auth is http/bearer. Model both in components.securitySchemes and apply security per-operation, following the site's "Authentication" chapter.

6. CI pipeline shape

composer test                     # includes schema assertions
php artisan scramble:export       # regenerate artefact
redocly lint openapi.yaml         # validity + style ruleset
oasdiff breaking --fail-on ERR    # block breaking changes on PRs

Version the spec with the same tag as the API (/api/v1 → openapi/v1.yaml) so historical contracts stay retrievable.

Gotchas and Tips

• There is no package to install. No composer.json, no PHP source, no runtime. If a task tracker says "add oai/learn.openapis.org", the correct action is "link the docs" — not "add a dependency." The 237 stars and CC-BY-4.0 licence are signals of a documentation repo.
• 3.0 vs 3.1 is the biggest trap. In 3.1 nullable: true is gone (use type: ['string', 'null']), exclusiveMinimum is a number not a boolean, and example on schemas is discouraged in favour of examples. Tooling — including some PHP generators and older Swagger UI builds — still lags on 3.1. Pick 3.0.x unless you have a reason.
• $ref does not survive naive tooling. redocly bundle or swagger-cli bundle before feeding the spec to generators that cannot resolve external files. Keep everything in one file, or bundle in CI.
• FormRequest rules ≠ JSON Schema. required, sometimes, nullable, and Rule::in map cleanly, but conditional rules (required_if, exclude_unless) and bail do not. Document the effective contract, and prefer a dedicated StoreOrderRequest per operation so the schema stays honest.
• Laravel error responses are easy to under-specify. ValidationException returns 422 with {message, errors}, auth failures return 401 with {message}, and unhandled exceptions can return HTML in non-JSON contexts. Document a shared Error schema in components and reference it from a global default response — otherwise consumers hit undocumented shapes on day one.
• Pagination envelopes drift. If you use Resource::collection, the wrapper is {data: [...], links: {...}, meta: {...}}. Write that explicitly as a PaginatedResponse component and allOf it into each list endpoint.
• Docs routes leak in production. Gate /docs and the raw spec behind auth or an APP_ENV !== 'production' check, and set Cache-Control on the YAML — it is not sensitive, but it is also not something you want re-fetched per page view.
• CORS on the spec endpoint. If a separately-hosted Swagger UI or a browser-based client generator fetches /openapi.yaml, it needs Access-Control-Allow-Origin. Route it through the api middleware group or add the header explicitly.
• Example values beat descriptions. The site repeatedly stresses examples over prose; reviewers and client generators both read examples far more reliably than paragraph descriptions. Put a realistic payload in every request body and every response.
• Custom Spectral rules are the extension point. learn.openapis.org will not enforce your house style (naming, error envelope, versioning headers). Fork the spectral:oas ruleset and add rules like operation-operationId-unique, "all responses must reference #/components/responses/Error", and "every operation must declare security".
• Treat the site as versioned reference material. It tracks the current spec; older chapters may describe 3.0 syntax after a 3.1 rewrite. When in doubt, the normative source is the spec itself (OAI/OpenAPI-Specification), not the learning site — cite the site for onboarding, the spec for arbitration.