organiseyou/openapi-generator

Library to generate openapi specification

v1.3 2025-10-16 08:29 UTC

Requires

• php: ^8.2

Requires (Dev)

• phpunit/phpunit: ^8.5
• squizlabs/php_codesniffer: ^3.5

MIT

• Joris Ros

README

A lightweight, fluent PHP service for generating OpenAPI 3.0.0 specifications programmatically. Perfect for Laravel and standalone PHP applications.

Installation

composer require organiseyou/openapi-generator

Quick Start

<?php

use OrganiseYou\OpenApi\OpenApiService;

$api = new OpenApiService(
    title: 'My API',
    version: '1.0.0',
    description: 'My awesome API',
    basePath: '/api/v1'
);

// Define a schema
$api->schema('User')
    ->type('object')
    ->property('id', 'integer', ['description' => 'User ID'])
    ->property('name', 'string', ['maxLength' => 255])
    ->property('email', 'string', ['format' => 'email'])
    ->required(['id', 'name', 'email'])
    ->register();

// Define an endpoint
$api->path('/users')
    ->method('GET')
    ->summary('List all users')
    ->tags(['Users'])
    ->response(200, [
        'description' => 'Successful response',
        'content' => [
            'application/json' => [
                'schema' => [
                    'type' => 'array',
                    'items' => ['$ref' => '#/components/schemas/User']
                ]
            ]
        ]
    ])
    ->register();

// Generate the specification
$spec = $api->toJson();

Core Features

Schemas

Define reusable data structures with the schema() method:

$api->schema('Product')
    ->type('object')
    ->property('id', 'integer', ['example' => 1])
    ->property('name', 'string', ['maxLength' => 255])
    ->property('price', 'number', ['format' => 'float', 'example' => 29.99])
    ->property('description', 'string', ['nullable' => true])
    ->required(['id', 'name', 'price'])
    ->description('A product in the catalog')
    ->example([
        'id' => 1,
        'name' => 'Widget',
        'price' => 29.99,
        'description' => 'A useful widget'
    ])
    ->register();

Dynamic Properties with Loops

Add properties dynamically from arrays or databases:

$userSchema = $api->schema('User')->type('object');

$properties = [
    'id' => ['type' => 'integer', 'example' => 10],
    'username' => ['type' => 'string', 'example' => 'john_doe'],
    'email' => ['type' => 'string', 'example' => '[e-mail]'],
    'status' => ['type' => 'string', 'enum' => ['active', 'inactive']],
];

foreach ($properties as $name => $config) {
    $type = $config['type'];
    unset($config['type']);
    $userSchema->property($name, $type, $config);
}

$userSchema->required(['id', 'username', 'email'])->register();

Endpoints with Full Documentation

Define API endpoints with parameters, request bodies, and responses:

$api->path('/users/{id}')
    ->method('GET')
    ->summary('Get a specific user')
    ->description('Retrieve a user by their ID')
    ->tags(['Users'])
    ->parameters([
        [
            'name' => 'id',
            'in' => 'path',
            'required' => true,
            'schema' => ['type' => 'integer'],
            'description' => 'User ID'
        ]
    ])
    ->response(200, [
        'description' => 'User found',
        'content' => [
            'application/json' => [
                'schema' => ['$ref' => '#/components/schemas/User']
            ]
        ]
    ])
    ->response(404, ['description' => 'User not found'])
    ->register();

POST with Request Body

$api->path('/users')
    ->method('POST')
    ->summary('Create a new user')
    ->tags(['Users'])
    ->requestBody([
        'application/json' => [
            'schema' => ['$ref' => '#/components/schemas/User']
        ]
    ], true)
    ->response(201, [
        'description' => 'User created',
        'content' => [
            'application/json' => [
                'schema' => ['$ref' => '#/components/schemas/User']
            ]
        ]
    ])
    ->response(400, ['description' => 'Invalid input'])
    ->register();

Multiple Methods on Same Path

$api->path('/users')
    ->method('GET')
    ->summary('List users')
    ->response(200, ['description' => 'Success'])
    ->register()
    ->path('/users')
    ->method('POST')
    ->summary('Create user')
    ->response(201, ['description' => 'Created'])
    ->register();

Reusable Response Components

$api->addResponse('NotFound', [
    'description' => 'Resource not found',
    'content' => [
        'application/json' => [
            'schema' => ['$ref' => '#/components/schemas/Error']
        ]
    ]
]);

$api->addResponse('Unauthorized', [
    'description' => 'Unauthorized access',
    'content' => [
        'application/json' => [
            'schema' => ['$ref' => '#/components/schemas/Error']
        ]
    ]
]);

Output Formats

JSON Output

$json = $api->toJson();
// or with custom flags:
$json = $api->toJson(JSON_PRETTY_PRINT);

Generate Array

$spec = $api->generate();

YAML Output

Requires symfony/yaml:

composer require symfony/yaml

$yaml = $api->toYaml();

Laravel Integration

Service Provider Setup

Create a route to serve your API documentation:

// routes/api.php

Route::get('/docs', function () {
    $api = new OpenApiService('My API', '1.0.0');
    
    // Define your schemas and endpoints
    $api->schema('User')->type('object')->property('id', 'integer')->register();
    $api->path('/users')->method('GET')->response(200, [])->register();
    
    return response()->json($api->generate());
});

In a Service Class

namespace App\Services;

use OrganiseYou\OpenApi\OpenApiService;

class ApiDocumentationService
{
    public static function generate(): OpenApiService
    {
        $api = new OpenApiService(
            title: config('app.name'),
            version: '1.0.0',
            basePath: '/api/v1'
        );

        // Define your schemas and endpoints here
        self::defineUserSchema($api);
        self::defineUserEndpoints($api);

        return $api;
    }

    private static function defineUserSchema(OpenApiService $api): void
    {
        $api->schema('User')
            ->type('object')
            ->property('id', 'integer')
            ->property('name', 'string')
            ->property('email', 'string')
            ->required(['id', 'name', 'email'])
            ->register();
    }

    private static function defineUserEndpoints(OpenApiService $api): void
    {
        $api->path('/users')
            ->method('GET')
            ->summary('List users')
            ->response(200, [
                'description' => 'Success',
                'content' => [
                    'application/json' => [
                        'schema' => [
                            'type' => 'array',
                            'items' => ['$ref' => '#/components/schemas/User']
                        ]
                    ]
                ]
            ])
            ->register();
    }
}

Then use it in a controller:

namespace App\Http\Controllers;

use App\Services\ApiDocumentationService;

class ApiDocumentationController extends Controller
{
    public function show()
    {
        $api = ApiDocumentationService::generate();
        return response()->json($api->generate());
    }
}

Complete Example

<?php

use OrganiseYou\OpenApi\OpenApiService;

$api = new OpenApiService(
    title: 'Pet Store API',
    version: '1.0.0',
    description: 'A simple Pet Store API',
    basePath: '/api/v1'
);

// Define schemas
$api->schema('Pet')
    ->type('object')
    ->property('id', 'integer', ['example' => 1])
    ->property('name', 'string', ['example' => 'Fluffy'])
    ->property('status', 'string', ['enum' => ['available', 'sold']])
    ->required(['id', 'name'])
    ->register();

$api->schema('Error')
    ->type('object')
    ->property('code', 'string')
    ->property('message', 'string')
    ->required(['code', 'message'])
    ->register();

// Define endpoints
$api->path('/pets')
    ->method('GET')
    ->summary('List all pets')
    ->tags(['Pets'])
    ->response(200, [
        'description' => 'List of pets',
        'content' => [
            'application/json' => [
                'schema' => [
                    'type' => 'array',
                    'items' => ['$ref' => '#/components/schemas/Pet']
                ]
            ]
        ]
    ])
    ->register()
    ->path('/pets')
    ->method('POST')
    ->summary('Create a pet')
    ->tags(['Pets'])
    ->requestBody([
        'application/json' => [
            'schema' => ['$ref' => '#/components/schemas/Pet']
        ]
    ])
    ->response(201, [
        'description' => 'Pet created',
        'content' => [
            'application/json' => [
                'schema' => ['$ref' => '#/components/schemas/Pet']
            ]
        ]
    ])
    ->register();

// Get the specification
$spec = $api->toJson();
echo $spec;

API Reference

OpenApiService

• addPath(string $path, string $method, array $operation): self
• addSchema(string $name, array $schema): self
• addResponse(string $name, array $response): self
• path(string $path): PathBuilder
• schema(string $name): SchemaBuilder
• generate(): array
• toJson(int $flags = JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT): string
• toYaml(): string

PathBuilder

• method(string $method): self
• summary(string $summary): self
• description(string $description): self
• tags(array $tags): self
• parameters(array $parameters): self
• requestBody(array $content, bool $required = true): self
• response(int|string $status, array $response): self
• register(): OpenApiService

SchemaBuilder

• type(string $type): self
• property(string $name, string $type, array $options = []): self
• required(array $fields): self
• description(string $description): self
• example(array $example): self
• register(): OpenApiService

License

MIT