Introduction

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

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

Installing

You can install the package via composer:

composer require goldspecdigital/oooas

Example

See the code sample below for the most basic usage:

use GoldSpecDigital\ObjectOrientedOAS\Objects\{
    Info, MediaType, Operation, PathItem, Paths, 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::UUID),
        Schema::string('name'),
        Schema::integer('age')->example(23),
        Schema::string('created_at')->format(Schema::DATE_TIME)
    );
    
// Create the user response.
$userResponse = Response::create()
    ->statusCode(200)
    ->description('OK')
    ->content(MediaType::json($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.
$userPaths = PathItem::create()
    ->route('/users')
    ->operations($showUser);
    
// Define all of the paths supported by the API.
$paths = Paths::create()
    ->pathItems($userPaths);
    
// Create the main OpenAPI object composed off everything created above.
$openApi = OpenApi::create()
    ->version(OpenApi::VERSION_3_0_1)
    ->info($info)
    ->paths($paths)
    ->tags($usersTag);
    
header('Content-Type: application/json');
echo $openApi->toJson();

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.1
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

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

If you want to learn more about the OpenAPI schema, or if you would like a quick reference, then check out the OpenAPI Map project created by Arnaud Lauret.

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

Running the tests

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

# Code style tests.
php vendor/bin/phpcs

# Unit tests.
php vendor/bin/phpunit

Contributing

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

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• GoldSpec Digital

See also the list of contributors who participated in this project.

License

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