oooas

oooas (Object Oriented OpenAPI Specification) is a dependency-free PHP library that lets you construct OpenAPI/Swagger specifications programmatically using a fluent, object-oriented API instead of hand-writing large JSON or YAML documents. Every part of the spec, from paths and operations to schemas, parameters, and responses, is modeled as an immutable object you compose and then serialize.

Because the spec is built in code, it stays type-checked, refactorable, and reusable, and can be exported to JSON or YAML for tooling, documentation, or contract testing.

What You Get

• A fluent, immutable object model covering the OpenAPI 3.x specification
• Builder objects for paths, operations, parameters, request bodies, and responses
• Reusable schema objects for describing request and response payloads
• Serialization of the assembled spec to array, JSON, or YAML
• Zero runtime dependencies

Common Use Cases

• Generating an OpenAPI document from application code as the single source of truth
• Producing Swagger docs without maintaining a large hand-written YAML file
• Building spec fragments dynamically from routes or models
• Feeding generated specs into contract testing or client-generation tooling

Under The Hood

Architecture - The library centers on the OpenApi root object under src/OpenApi.php, with the full spec modeled as immutable value objects in src/Objects (Operation, PathItem, Schema, Response, Parameter, etc.), shared behavior in src/Contracts and helpers in src/Utilities. Each object exposes static create() factories and with*() chainable mutators that return new instances, and a toArray()/toJson()/toYaml() path handles serialization.

Tech Stack - Pure PHP with no runtime dependencies; tests run under PHPUnit via GitHub Actions.

Code Quality - The codebase is consistently structured around one class per OpenAPI object and ships a test suite exercising object construction and serialization, giving a predictable, easy-to-audit surface.

API Design - The immutable, chainable builder pattern is highly ergonomic: IDEs autocomplete the available with* methods, invalid specs surface as PHP type errors early, and composing reusable schema objects reduces duplication compared with raw YAML.