# Specifications

The built-in OpenAPI specification generation feature allows you to produce the specifications with absolutely no code changes required.

php artisan orion:specs

The command will create specs.json file inside the storage/app/specs directory.

# Customizations

# Info and Servers

Specifications' info and servers fields are populated from the orion.php config file:

'specs' => [
    'info' => [
        'title' => env('APP_NAME'),
        'description' => null,
        'terms_of_service' => null,
        'contact' => [
            'name' => null,
            'url' => null,
            'email' => null,
        ],
        'license' => [
            'name' => null,
            'url' => null,
        ],
            'version' => '1.0.0',
    ],
    'servers' => [
        ['url' => env('APP_URL').'/api', 'description' => 'Default Environment'],
    ],
],

TIP

If you haven't published the config yet, you can do so by running the following command:

php artisan vendor:publish --tag=orion-config

# File Path

If you would like the file to be stored at a different path (e.g. storage/app/specs/example.yaml), you can easily customize it by providing the --path option.

# Please note that the given path is a relative path

php artisan orion:specs --path="specs/example.yaml"

# File Format

By default, the specifications file is stored in .yaml format. However, it is possible to store it in .json, simply by providing the --format option.

php artisan orion:specs --format="json"

TIP

If you already have custom endpoints and their OpenAPI specifications, simply put the existing specification file anywhere inside the storage/app directory and provide the --path option to the command. It will generate specifications for the standard endpoints and merge them with the existing (custom) ones.

# Please note that the given path is a relative path

php artisan orion:specs --path="specs/existing-specs.yaml"

NOTE

As of now, the generator supports only the standard (provided by Laravel Orion) endpoints. Specifications, for any custom endpoints you create, won't be generated. However, there are plans to make it possible in the next releases.

Last Updated: 2/24/2024, 10:37:01 AM