You can use plugins as an alternative way to provide Scribe with more information about your endpoints.
For instance, suppose all your GET endpoints support pagination query parameters
page, and you don't want to annotate with
@queryParam on each method. You can create a plugin that adds this to all your query parameters. Let's see how to do this.
First, it's important to know the stages of route processing:
- metadata (this includes
groupDescription, and authentication status (
- headers (headers to be added to example requests and response calls)
- responseFields (descriptions of fields in the response)
At each stage, the Extractor attempts to use various "strategies" to fetch data. The Extractor will call all the strategies configured in
scribe.php, merging their results together to produce the final output of that stage. Later strategies can overwrite or add to the results of earlier strategies.
Unlike other stages, the
responses stage is additive. This means that all responses from all strategies will be saved. Responses cannot overwrite each other, even if they have the same status code. By contrast, if you return a value for a body parameter from one strategy, it will overwrite any data for that parameter gotten from previous strategies.
There are a number of strategies included with the package, so you don't have to set up anything to get it working.
Check out our community wiki for a list of strategies contributed by the community.
To create a strategy, create a class that extends
\Knuckles\Scribe\Extracting\Strategies\Strategy. You can do this manually, or by running the
This will create a class like this in your
Alternatively, if you're creating a strategy that you'd like people to download and install via Composer, you can generate one from this GitHub template.
Let's take a look at the contents of our Strategy class. There's a detailed plugin API reference (and you should check it out), but the important thing is the
__invoke method. This is where our logic goes.
Let's add some code to make our strategy work:
So what's going on here? We're checking if the endpoint if a GET endpoint using the
$endpointData object. Then we also check for the route name, via
$endpointData->route. And finally we return the parameter info.
Note that we set our
reuired => false and
example => null. This tells Scribe to omit it from example requests. It will still be present in the main docs.
The final step is to register the strategy in our config:.
You can also publish your strategy as a Composer package. Then others can install them via
composer require and register them in their own config.
And we're done! Now, when we run
php artisan scribe:generate, all our GET routes that end with
.index will have the pagination parameters added. Here we go!
See the plugin API reference for details of what's available when writing plugins.
When developing strategies, you have access to a few useful tools:
You can use the
RouteDocBlocker class to fetch docblocks for a route (method and class). It has this interface:
You pass in a route (from
$endpointData->route), and you get an array with two keys,
class, containing the docblocks for the method and controller handling the route respectively (instances of
This allows you to implement your own custom tags. For instance, a
And in your controller method: