Plugin API

Plugins (custom strategies) allow you to provide Scribe with more information about your endpoints. This document describes the plugin API. For a guide to creating plugins, see Writing Plugins.

Each plugin must extend the base strategy class, Knuckles\Scribe\Extracting\Strategies\Strategy, which is an abstract class defined like this:

use Knuckles\Camel\Extraction\ExtractedEndpointData;
use Knuckles\Scribe\Tools\DocumentationConfig;

abstract class Strategy
{
    /**
     * The Scribe config
     */
    protected DocumentationConfig $config;
    
    /**
     * @param ExtractedEndpointData $endpointData
     * @param array $routeRules Array of rules for this route.
     *
     * @return array|null
     */
    abstract public function __invoke(
        ExtractedEndpointData $endpointData,
        array $routeRules = []
    ): ?array;
}

tip

You can run php artisan scribe:strategy <className> to automatically generate a strategy.

$config

The $config property is an instance of the Scribe configuration (= config('scribe')). You can retrieve values using get() and dot notation. For example:

// Check if "Try It Out" is enabled:
$this->config('try_it_out.enabled');

You can specify a default that will be returned if the value does not exist. Otherwise, null will be returned.

$this->config('unknown_setting'); // Returns null
$this->config('unknown_setting', true); // Returns true

__invoke(ExtractedEndpointData $endpointData, array $routeRules): ?array

This is the method that is called to process a route. Parameters:

• $endpointData, an instance of Knuckles\Camel\Extraction\ExtractedEndpointData (source), which contains information about the endpoint being processed.
• $routeRules, the rules passed in the apply section of the Scribe config for this route.

This method may return null or an empty array if it has no data to add. Otherwise, it should return an array with the relevant information, which varies depending on the type of strategy/stage of route processing:

• For metadata, a map (key => value) of metadata attributes (as shown in the example below). If you'd like to set a custom attribute so you can access it later, you can add items to the $endpointData->metadata->custom array directly.

  return [
    'groupName' => 'User management',
    'groupDescription' => 'APIs to manage users.',
    'title' => 'Shadowban a user',
    'description' => "Temporarily restrict a user's account",
    'authenticated' => true,
    'custom' => [],
  ];

• For headers, a map (key => value) of headers and values.

  return [
    'Api-Version' => null,
    'Content-Type' => 'application/xml',
  ];

• For urlParameters, queryParameters, and bodyParameters, a map (key => value) of parameters. Each parameter may specify a type, description, example, and a required flag.

  return [
    'room_id' => [
      'type' => 'string',
      'description' => '',
      'example' => 'r4oiu78t63ns3',
      'required' => true, 
    ]
  ];

  You may also add any custom data you wish to pass around in a custom field.

  return [
    'submission_date' => [
      'type' => 'string',
      'example' => '2021-02-03T01:00:00Z',
      'required' => true, 
      'custom' => [
        'format' => 'datetime'
      ]
    ]
  ];

note

Setting a parameter to required => false and example => null tells Scribe to omit it from example requests. It will still be present in the main docs.

• For responses, a list of one or more responses.

  return [
    [
      'status' => 201,
      'headers' => ['sample-header' => 'sample-value'],
      'description' => 'Operation successful.',
      'content' => '{"room": {"id": "r4oiu78t63ns3"}}',
    ],
  ];

note

The return values from each strategy are merged with the existing extracted data. This means a later strategy can overwrite an earlier one. The exception here is the responses stage. The responses from all strategies will be kept. Responses will not overwrite each other, even if they have the same status code.

If you need to overwrite previous responses, modify the $endpointData->responses object directly (but this is at your own risk).