API: OpenAPI

The API package includes OpenAPI schema generation and a docs view.

OpenAPI Config

The JSON schema route has its own middleware. By default, ['web', 'auth'] requires a signed-in Laravel session. If a trusted tool needs to fetch the schema with a Sanctum token, change the middleware entry inside the existing openapi array in config/seviaflow-api.php:

'middleware' => ['api', 'auth:sanctum'],

This protects the JSON route with the API guard. The rendered api-docs page uses the separate docs.middleware setting; keep both routes authenticated as appropriate for your application.

Routes

With defaults, schema output is available at GET /api/admin/openapi.json with route name seviaflow.api.openapi. The docs view is available at GET /api/admin/api-docs with route name seviaflow.api.docs.

Generated Schema

SeviaFlow\Api\OpenApi\OpenApiGenerator generates OpenAPI 3.1.0. The playground integration test verifies the generated spec includes customer resource paths such as /api/admin/resources/customers.

Form field declarations provide the default field schema. A headless resource or an individual override uses ApiResource::schema(['field' => ['type' => 'string']]). The generator does not infer UUID, invoice number, money or collection semantics from column names. Money values are represented as decimal strings with currency and scale metadata from MoneyField.

OpenAPI operations are emitted only when the same enabled/readable/creatable/updatable/deletable/flow capability used by runtime routing is active. Resource operations document 401, 403, 404, 409 and 422 responses; validation errors use an errors object whose keys preserve nested request paths.

For a headless Resource or a field whose type cannot be inferred from a form field, declare an explicit schema in the Resource's api() method:

use SeviaFlow\Core\Resources\ApiResource;

// Inside your Resource class:
public static function api(ApiResource $api): ApiResource
{
    return $api
        ->enabled()
        ->readable(['uuid', 'total'])
        ->schema([
            'uuid' => ['type' => 'string', 'format' => 'uuid'],
            'total' => ['type' => 'string', 'format' => 'decimal'],
        ]);
}

The field names in readable() must exist on the model and be allowed by the API contract. Explicit schema values override guesses based on names; SeviaFlow does not infer UUID or decimal meaning from a column name alone.

Security Scheme

The generated spec declares a bearer security scheme for API operations. This describes how callers authenticate to the Resource API; it does not set middleware on the OpenAPI JSON or docs routes. Configure those routes separately with openapi.middleware and docs.middleware.