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
        [
            'export_filename' => 'public-api.json',
            'routes' => [
                '/api/public',
            ],
        ]
    ],

It is recommended to set a key for each workspace in this array but it is not required. Here are the benefits of setting a key:

• You can omit export_filename setting to use workspace key as a file name (e.g., documents-api → documents-api.json)
• If you are using autodoc-laravel package, you can use autodoc:export {workspace} command to generate an OpenApi schema file for the specified workspace key (with progress tracking and better error reporting).

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