Weave Code
Openapi Specification Laravel Package
oai/openapi-specification
The OpenAPI Specification is the official, language-agnostic standard for describing RESTful APIs. It lets humans and machines discover and understand a service's capabilities without source code, docs, or traffic inspection, making it foundational for API tooling in PHP and Laravel projects.
The OpenAPI Specification defines a standard, language-agnostic interface for RESTful APIs, letting both humans and machines discover and understand a service without access to its source code. It is the vendor-neutral contract behind most modern API tooling.
Maintained by the OpenAPI Initiative, it is the de facto standard for describing HTTP APIs.
- Schema-first design for APIs
- Rich ecosystem of docs, codegen, and testing tools
- Vendor-neutral governance
- Covers OpenAPI 3.x and legacy 2.0
- Language-agnostic, JSON/YAML-based
Frequently asked questions about Openapi Specification
- Is oai/openapi-specification a Laravel package or a Composer dependency?
- No. oai/openapi-specification is the upstream OpenAPI Specification repository, not a Laravel or PHP package; it has no composer.json, service provider, runtime API, or Composer autoload surface. Laravel teams consume it indirectly through PHP tools that implement or validate the spec.
- How do I install oai/openapi-specification in a Laravel app?
- You do not install it with composer require in a Laravel app. At most, an organization vendors the JSON Schema files or pins a spec version tag or commit SHA for offline validation. The actual Composer dependencies are the PHP generators, parsers, and validators you choose.
- Which OpenAPI version should Laravel teams use: 3.0.3, 3.1, or 3.2?
- Use OpenAPI 3.0.3 as the safe default for Laravel work because PHP tooling supports it most consistently. OpenAPI 3.1.x aligns with JSON Schema 2020-12 and adds webhooks, but PHP validator support is uneven and can surface edge cases. Treat OpenAPI 3.2 as bleeding edge and out of scope for a first adoption.
- What Laravel and PHP versions work with OpenAPI tooling?
- There is no Laravel version constraint from the spec itself because it is language-agnostic and has no runtime code. In practice, Laravel 10, 11, and 12 on PHP 8.1+ are common with tools such as Scribe, swagger-php, cebe/php-openapi, and league/openapi-psr7-validator. Check each tool's own compatibility matrix before pinning versions.
- Should Laravel teams use design-first or code-first OpenAPI?
- Both approaches work, but code-first is the faster starting point for existing Laravel apps. Generate an initial spec from routes with Scribe or swagger-php, expect roughly 60–70% fidelity, then hand-curate auth schemes, error envelopes, and response schemas. Design-first gives cleaner contracts but requires clear ownership of the spec artifact.
- Which PHP tools generate or validate OpenAPI specs for Laravel?
- Common PHP options include knuckleswtf/scribe and zircote/swagger-php for generation, cebe/php-openapi and league/openapi-psr7-validator for parsing and validation, and Spectral for linting. oasdiff helps detect breaking changes in CI, while openapi-generator or orval can produce client SDKs. These tools complement the upstream spec rather than replacing it.
- Can I use the upstream OpenAPI JSON Schemas for validation in CI?
- Yes, you can vendor the upstream JSON Schema dialect files or pin a known spec tag or commit SHA and run validation in CI. That catches structural and schema problems, but it does not prove the spec matches your Laravel implementation. Pair schema validation with contract tests and review for semantic drift.
- Does OpenAPI 3.1 work with PHP validators like cebe/php-openapi?
- Support is uneven. OpenAPI 3.1 features such as JSON Schema 2020-12 alignment and type arrays can expose gaps or edge cases in PHP validators, so test your exact toolchain end-to-end. If you need predictable validation, stay on 3.0.3 until your generator and validator both advertise full 3.1 support.
- Is oai/openapi-specification safe for production Laravel applications?
- It is not a runtime production dependency, so it should not be in your deployed Laravel application's Composer requirements. Use it as a design-time and CI-time contract artifact, pin the version or commit you validate against, and review breaking changes before upgrading. Production risk comes from version skew and false confidence, not from the repo executing code.
- Is oai/openapi-specification maintained, and why is there a 2026 release date?
- The stated last release date of 2026-09-10 is anomalous, so treat release metadata as unreliable and pin to a known tag or commit SHA rather than tracking HEAD. The spec also moves independently of PHP tooling, so maintenance should be judged by your chosen generator and validator support. Do not assume a valid spec is a correct spec; keep human review in the loop.
Weaver
How can I help you explore Laravel packages today?