Customize OpenAPI documents

Document transformers

Document transformers allow you to modify the resulting OpenAPI document after it was generated. It is useful to add auth information, add another meta information to the document, or modify the resulting document entirely.

A document transformer is an instance of a class implementing Dedoc\Scramble\Contracts\DocumentTransformer interface, or a closure that accepts a document and an OpenAPI context (Dedoc\Scramble\OpenApiContext) that holds the document generation configuration and the list of references.

You add document transformers using the withDocumentTransformers method on the API configuration object.

This method accepts:

• A name of a class implementing DocumentTransformer contract.
• A closure that accepts a document.
• An array of transformers.
• A closure that accepts Dedoc\Scramble\Configuration\DocumentTransformers object which allows you to explicitly specify the order of transformers.

For example, here is how you can pass the closure:

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(function (OpenApi $document) {
            $document->info->description = 'API for the best Todo app!';
        });
}

Document transformers are applied sequentially. If you need to define the order, you can use the closure that accepts the configuration object. It has append and prepend methods that allow you to define the order. These methods can also accept a name of a transformer class, a closure, or an array of document transformers.

use Dedoc\Scramble\Configuration\DocumentTransformers;

public function boot()
{
    Scramble::configure()
        ->withDocumentTransformers(function (DocumentTransformers $transformers) {
            $transformers
                ->prepend(AddAuthInfo::class)
                ->append(AddOperationAuthInfo::class);
        });
}

Operation transformers

Operation transformers allow you to modify the OpenAPI operations after they were generated. This is useful to apply some changes to all operations of the API, or to modify a specific operation. For example, you can add common headers to the operation, or exclude a single specific operation from the auth requirements, etc.

Operation transformer is an instance of a class implementing Dedoc\Scramble\Contracts\OperationTransformer interface, or a closure that accepts an operation and its context: the route information.

To register operation transformations, use withOperationTransformations configuration’s method.

It accepts:

• A name of a class implementing OperationTransformer contract.
• A closure that accepts an operation and the route information.
• An array of operation transformers.
• A closure that accepts Dedoc\Scramble\Configuration\OperationTransformers object which allows you to explicitly specify the order of transformers.

For example, here is how you can register a closure operation transformer that adds a header to all API operations:

public function boot()
{
    Scramble::configure()
        ->withOperationTransformers(function (Operation $operation) {
            $operation->addParameters([
                new Parameter('X-Rate-Limited', 'header'),
            ]);
        });
}

Operation transformers are applied sequentially. If you need to define the order, you can use the closure that accepts the configuration object. It has append and prepend methods that allow you to define the order. These methods can also accept a name of a transformer class, a closure, or an array of operation transformers.

Under the hood Scramble generates the API documentation using operation transformers as well. So you can register your own operation transformer that will be executed before all the internal transformers.

use Dedoc\Scramble\Configuration\OperationTransformers;

public function boot()
{
    Scramble::configure()
        ->withOperationTransformers(function (OperationTransformers $transformers) {
            $transformers
                ->prepend(ResolveContainerBindings::class)
                ->append(AddHeaderParameters::class);
        });
}