Workspaces

Use workspaces to generate separate OpenAPI schemas for different parts of your application.

You can define multiple workspaces in your config file:

    'workspaces' => [
        // Workspace 1
        'documents-api' => [
            'routes' => [
                '/api/auth',
                '/api/documents',
            ],
            'access_token' => 'secret-api-access-token-E6T3xfdCvW9B',
        ],
        // Workspace 2
        'billing-api' => [
            'routes' => [
                '/api/auth',
                '/api/billing',
            ],
            'access_token' => 'secret-api-access-token-GQXcNqs5zfPm',
        ],
        // Workspace 3
        'default' => [
            'export_filename' => 'public-api.json',
            'routes' => [
                '/api/public',
            ],
        ]
    ],

If you omit export_filename setting, workspace key will be used as a file name (e.g., documents-api → documents-api.json).

To define workspaces in separate files, set workspaces_json_dir to a directory containing one <key>.json file per workspace. Each file has the same structure as an inline entry, and its filename becomes the workspace key. Inline entries take precedence when the same key exists in both places.

Exporting workspace OpenAPI JSON”

OpenAPI JSON files are generated automatically when you visit the documentation route. However, you can also export them using the command below.

For Laravel:

php artisan autodoc:openapi {workspace}

For other PHP projects:

vendor/bin/autodoc openapi {workspace} --config="/path/to/your/autodoc/config.php"

Default workspace

The default workspace is the first workspace which does not have an access_token setting. In the example above that would be "Workspace 3" which includes all routes that start with '/api/public'.

$workspace = AutoDoc\Workspace::getDefault($config);

$openApiSchemaJson = $workspace->getJson();

Workspaces with access tokens

If a workspace has a configured access_token, it will be accessible only using the provided token.

$workspace = AutoDoc\Workspace::findUsingToken($accessToken, $config);

Usage example

Here is a simple implementation of using Workspace class to get an OpenAPI JSON schema. This example is based on the logic that is used in autodoc-laravel package.

use AutoDoc\Config;
use AutoDoc\Workspace;
use Illuminate\Http\Response;

class OpenApiController
{
    public function getJson(): Response
    {
        $config = new Config(config('autodoc'));
        $accessToken = request('token');

        if ($accessToken) {
            $workspace = Workspace::findUsingToken($accessToken, $config);

        } else {
            $workspace = Workspace::getDefault($config);
        }

        if (! $workspace) {
            abort(404);
        }

        return response($workspace->getJson(), 200)
            ->header('Content-Type', 'application/json');
    }
}