PHPackages                             goldspecdigital/oooas - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. goldspecdigital/oooas

ActiveLibrary[API Development](/categories/api)

goldspecdigital/oooas
=====================

An object oriented approach to generating OpenAPI specs, implemented in PHP.

v2.10.0(3y ago)2322.8M↑11.1%27[15 issues](https://github.com/goldspecdigital/oooas/issues)[4 PRs](https://github.com/goldspecdigital/oooas/pulls)20MITPHPPHP >=7.1.0

Since Sep 27Pushed 3y ago7 watchersCompare

[ Source](https://github.com/goldspecdigital/oooas)[ Packagist](https://packagist.org/packages/goldspecdigital/oooas)[ Docs](https://github.com/goldspecdigital/oooas)[ RSS](/packages/goldspecdigital-oooas/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (3)Versions (28)Used By (20)

 [![Object Oriented OpenAPI Specification](https://camo.githubusercontent.com/053dacb6893be524379d039dcef60bd15b25f5279e5a7fe714344737f99f3e50/68747470733a2f2f73766773686172652e636f6d2f692f4437302e737667)](https://github.com/goldspecdigital/oooas)

 [![GitHub stars](https://camo.githubusercontent.com/c65dc9c74e13e9729aedfb0fc8904a8b23e3551946af8a407b7db011e551cecb/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f73746172732f676f6c64737065636469676974616c2f6f6f6f61732e7376673f7374796c653d736f6369616c)](https://github.com/goldspecdigital/oooas)

 [![GitHub tag (latest SemVer)](https://camo.githubusercontent.com/fdc96b9c6573714f2d0be518b2c89ad0c6adabfa4d440349dbe97edcc66e6d51/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f7461672f676f6c64737065636469676974616c2f6f6f6f61732e737667)](https://github.com/goldspecdigital/oooas/tags) [![Build status](https://github.com/goldspecdigital/oooas/workflows/Tests/badge.svg)](https://github.com/goldspecdigital/oooas/actions) [![Packagist](https://camo.githubusercontent.com/4627a3f2db4bb1f2311634cd60e2f3d6187059efa6eeedbec2193448a71f3325/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f676f6c64737065636469676974616c2f6f6f6f61732e737667)](https://packagist.org/packages/goldspecdigital/oooas) [![PHP from Packagist](https://camo.githubusercontent.com/da3068f8da2a74c5bc8fc0ec210a33958c13f93e36452ff1d71ae95c047026e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f676f6c64737065636469676974616c2f6f6f6f61732e737667)](https://camo.githubusercontent.com/da3068f8da2a74c5bc8fc0ec210a33958c13f93e36452ff1d71ae95c047026e8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f676f6c64737065636469676974616c2f6f6f6f61732e737667) [![Dependency count](https://camo.githubusercontent.com/20f4b99a958aadb02ff273ac6428c17cf55c6b817657ed64b1c39c7f71955a0e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646570656e64656e636965732d302d627269676874677265656e2e737667)](https://camo.githubusercontent.com/20f4b99a958aadb02ff273ac6428c17cf55c6b817657ed64b1c39c7f71955a0e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f646570656e64656e636965732d302d627269676874677265656e2e737667) [![Packagist](https://camo.githubusercontent.com/5ff6c34fd16c8853b8b28b677dad6f0f4b044492f583977c0e5f1d30bc205b93/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f676f6c64737065636469676974616c2f6f6f6f61732e737667)](https://camo.githubusercontent.com/5ff6c34fd16c8853b8b28b677dad6f0f4b044492f583977c0e5f1d30bc205b93/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f676f6c64737065636469676974616c2f6f6f6f61732e737667)

Introduction
------------

[](#introduction)

An object oriented approach to generating OpenAPI specs, implemented in PHP.

You can build up your API spec using immutable PHP classes, and then export the spec to JSON (or YAML with the help of another package).

This package is **dependency free** and makes heavy use of **PHP 7 features**, mainly being **type hints** and enabling **strict types**. This should make your life a lot easier when working with a good IDE that can use this information.

Installing
----------

[](#installing)

You can install the package via composer:

```
composer require goldspecdigital/oooas
```

Example
-------

[](#example)

See the code sample below for the most basic usage:

```
use GoldSpecDigital\ObjectOrientedOAS\Objects\{
    Info, MediaType, Operation, PathItem, Response, Schema, Tag
};
use GoldSpecDigital\ObjectOrientedOAS\OpenApi;

// Create a tag for all the user endpoints.
$usersTag = Tag::create()
    ->name('Users')
    ->description('All user related endpoints');

// Create the info section.
$info = Info::create()
    ->title('API Specification')
    ->version('v1')
    ->description('For using the Example App API');

// Create the user schema.
$userSchema = Schema::object()
    ->properties(
        Schema::string('id')->format(Schema::FORMAT_UUID),
        Schema::string('name'),
        Schema::integer('age')->example(23),
        Schema::string('created_at')->format(Schema::FORMAT_DATE_TIME)
    );

// Create the user response.
$userResponse = Response::create()
    ->statusCode(200)
    ->description('OK')
    ->content(
        MediaType::json()->schema($userSchema)
    );

// Create the operation for the route (i.e. GET, POST, etc.).
$showUser = Operation::get()
    ->responses($userResponse)
    ->tags($usersTag)
    ->summary('Get an individual user')
    ->operationId('users.show');

// Define the /users path along with the supported operations.
$usersPath = PathItem::create()
    ->route('/users')
    ->operations($showUser);

// Create the main OpenAPI object composed off everything created above.
$openApi = OpenApi::create()
    ->openapi(OpenApi::OPENAPI_3_0_2)
    ->info($info)
    ->paths($usersPath)
    ->tags($usersTag);

header('Content-Type: application/json');
echo $openApi->toJson();
```

### YAML output

[](#yaml-output)

Using the same code above will output the following YAML:

> In this example, the YAML may seem simpler to look at, however once the spec starts to increase in size - the ability to reuse objects and split them into separate files easily will be a massive help.

```
openapi: 3.0.2
info:
  title: API Specification
  description: For using the Example App API
  version: v1
paths:
  "/users":
    get:
      tags:
      - Users
      summary: Get an individual user
      operationId: users.show
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    format: uuid
                    type: string
                  name:
                    type: string
                  age:
                    type: integer
                    example: 23
                  created_at:
                    format: date-time
                    type: string
tags:
- name: Users
  description: All user related endpoints
```

### Outputting as JSON or YAML

[](#outputting-as-json-or-yaml)

Built in output to YAML has been omitted on purpose to keep this package dependency free. However, you can easily convert the array to a YAML string using several open source packages. See below for an example of outputting to both JSON and YAML:

```
use GoldSpecDigital\ObjectOrientedOAS\OpenApi;
use Symfony\Component\Yaml\Yaml;

$openApi = OpenApi::create();

$json = $openApi->toJson();
$array = $openApi->toArray();
$yaml = Yaml::dump($array);
```

Guidance
--------

[](#guidance)

If you want to learn more about the OpenAPI schema, then have a look at the official [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md).

Alternatively, if you would like a quick reference, then check out the [OpenAPI Map](https://openapi-map.apihandyman.io/?version=3.0) project created by [Arnaud Lauret](http://apihandyman.io/).

You can use this interactive tool to figure out what objects go where and how they relate to one another.

Usage
-----

[](#usage)

### Setting and unsetting properties

[](#setting-and-unsetting-properties)

Each object has setter methods for it's supported properties. Most of these methods allow `null` values which will need to be explicitly passed (see the next example for how to unset using variadic setter methods). This will have the effect of unsetting the property:

```
$info = Info::create()
    ->title('Example API');

$openApi = OpenApi::create()
    ->info($info);
echo $openApi->toJson(); // '{"info": {"title": "Example API"}}'

$openApi = $openApi->info(null);
echo $openApi->toJson(); // '{}'
```

For variadic setter methods, if you call the method and don't supply any parameters, then this will have the effect of unsetting the property:

```
$path = PathItem::create()
    ->route('/users');

$openApi = OpenApi::create()
    ->paths($path);
echo $openApi->toJson(); // '{"paths": {"/users": []}}'

$openApi = $openApi->paths();
echo $openApi->toJson(); // '{}'
```

### Retrieving properties

[](#retrieving-properties)

You can easily retrieve a property using a magic getter. These have been implemented for all properties for every object. DocBlocks have been provided to give better auto-completion in IDEs:

```
$info = Info::create()->title('Example API');

echo $info->title; // 'Example API'
```

### Object ID

[](#object-id)

Every object has an optional `$objectId` property which is a `string` and can either be set in the class constructor or the preferred `create()` method. This property is used when a parent object needs to use a name for the children.

An example of this in use is when a schema object is composed of other schema properties:

```
$schema = Schema::create()
    ->type(Schema::TYPE_OBJECT)
    ->properties(
        Schema::create('username')->type(Schema::TYPE_STRING),
        Schema::create('age')->type(Schema::TYPE_INTEGER)
    );

echo $schema->toJson();
/*
{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  }
}
*/
```

If an object contains any helper creation methods, then these methods also allow you to specify the `$objectId` property as a parameter. The code sample below is functionally identical to the one above:

```
$schema = Schema::object()
    ->properties(
        Schema::string('username'),
        Schema::integer('age')
    );

echo $schema->toJson();
/*
{
  "type": "object",
  "properties": {
    "username": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    }
  }
}
*/
```

### $ref

[](#ref)

The use of `$ref` has been applied to every single object to use as you wish. You may substitute any object for a `$ref` by invoking the `ref()` static method on the object class:

```
$schema = AllOf::create()
    ->schemas(
        Schema::ref('#/components/schemas/ExampleSchema')
    );

echo $schema->toJson();
/*
{
  "allOf": [
    ["$ref": "#/components/schemas/ExampleSchema"]
  ]
}
*/
```

### Specification extensions

[](#specification-extensions)

You can add [specification extensions](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#specificationExtensions)to all objects:

```
$schema = Schema::create()
    ->x('foo', 'bar')
    ->x('items', Schema::array()->items(Schema::string()));

echo $schema->toJson();
/*
{
  "x-foo": "bar",
  "x-items": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}
*/

echo $schema->{'x-foo'}; // 'bar'
```

You can also unset specification extensions by invoking the `x()` method and only providing the key:

```
$schema = Schema::create()
    ->x('foo', 'bar')
    ->x('items', Schema::array()->items(Schema::string()));

$schema = $schema->x('foo');

echo $schema->toJson();
/*
{
  "x-items": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}
*/
```

To retrieve an array of all the specification extensions you can call the `$x`property:

```
$schema = Schema::create()
    ->x('foo', 'bar')
    ->x('items', Schema::array()->items(Schema::string()));

echo json_encode($schema->x);
/*
{
  "x-foo": "bar",
  "x-items": {
    "type": "array",
    "items": {
      "type": "string"
    }
  }
}
*/
```

### Validation

[](#validation)

In order to perform schema validation you must first install the `justinrainbow/json-schema` package:

```
composer require justinrainbow/json-schema:^5.2
```

Once installed, you may now make use of the `validate()` method on the `OpenApi`object:

```
$openApi = OpenApi::create();
$openApi->validate();
```

*If you haven't installed the `justinrainbow/json-schema` package and attempt to use the `validate()` method, then a `RuntimeException` will be thrown.*

If validation fails for the schema, then a `GoldSpecDigital\ObjectOrientedOAS\Exceptions\ValidationException` will be thrown. You can use the `getErrors()` method on this exception to retrieve all of the validation errors.

Running the tests
-----------------

[](#running-the-tests)

To run the test suite you can use the following commands:

```
# To run both style and unit tests.
composer test

# To run only style tests.
composer test:style

# To run only unit tests.
composer test:unit
```

If you receive any errors from the style tests, you can automatically fix most, if not all of the issues with the following command:

```
composer fix:style
```

Contributing
------------

[](#contributing)

Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

Versioning
----------

[](#versioning)

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/goldspecdigital/oooas/tags).

Authors
-------

[](#authors)

- [GoldSpec Digital](https://github.com/goldspecdigital)

See also the list of [contributors](https://github.com/goldspecdigital/oooas/contributors)who participated in this project.

License
-------

[](#license)

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md)file for details.

###  Health Score

47

—

FairBetter than 94% of packages

Maintenance19

Infrequent updates — may be unmaintained

Popularity60

Solid adoption and visibility

Community29

Small or concentrated contributor base

Maturity67

Established project with proven stability

 Bus Factor1

Top contributor holds 87.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~53 days

Recently: every ~239 days

Total

27

Last Release

1399d ago

Major Versions

v0.4.1 → v1.0.02019-05-16

v1.0.2 → v2.0.02019-05-19

### Community

Maintainers

![](https://www.gravatar.com/avatar/938193490dee7bff7e71bbf41eba0af6f0a57437212674640e5b637de880e0d3?d=identicon)[goldspecdigital](/maintainers/goldspecdigital)

---

Top Contributors

[![matthew-inamdar](https://avatars.githubusercontent.com/u/13454566?v=4)](https://github.com/matthew-inamdar "matthew-inamdar (55 commits)")[![vyuldashev](https://avatars.githubusercontent.com/u/1809081?v=4)](https://github.com/vyuldashev "vyuldashev (7 commits)")[![PrinsFrank](https://avatars.githubusercontent.com/u/25006490?v=4)](https://github.com/PrinsFrank "PrinsFrank (1 commits)")

---

Tags

oasopen-sourceopenapiswaggerphpswaggeropenapioas

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/goldspecdigital-oooas/health.svg)

```
[![Health](https://phpackages.com/badges/goldspecdigital-oooas/health.svg)](https://phpackages.com/packages/goldspecdigital-oooas)
```

###  Alternatives

[harmbandstra/swagger-ui-bundle

Exposes swagger UI inside your Symfony project through a route (eg. /docs)

42867.3k](/packages/harmbandstra-swagger-ui-bundle)[erasys/openapi-php

Open API 3.0 builder and validation library for PHP that helps you write valid specs.

2080.3k5](/packages/erasys-openapi-php)[scalar/laravel

Render your OpenAPI-based API reference

6183.9k2](/packages/scalar-laravel)[tobion/openapi-symfony-routing

Loads routes in Symfony based on OpenAPI/Swagger annotations

4219.5k](/packages/tobion-openapi-symfony-routing)[clever/clever-php

231.6k](/packages/clever-clever-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)