Workspaces

Workspaces allow you to generate multiple OpenApi schemas from 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).

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:export {workspace}

For other PHP projects:

vendor/bin/openapi-export {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 token

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');
    }
}