Migrating to v4
welcome to Scribe v4.👋 This guide will help you migrate from v3. Not much changed, so you should be done in less than 5 minutes. See the release blog post for the list of new features.
Requirements​
Scribe v4 requires PHP 8 and Laravel 8+. If you're on an older version, you'll need to upgrade.
Start​
Upgrade the package version (knuckleswtf/scribe
) in your composer.json
to ^4.0
and then install:
composer update knuckleswtf/scribe
Automated upgrade​
Scribe v4 comes with an upgrade tool that will make the needed changes to your config file and inform you of any manual changes you need to make yourself:
# See what changes will be made:
php artisan scribe:upgrade --dry-run
# Run the upgrade for real
php artisan scribe:upgrade
The tool will back up your old config to config/scribe.php.bak
so you can restore it if something wasn't set correctly.
tip
If you use multi-docs, you can run the upgrade command for each of your config files, for instance php artisan scribe:upgrade --config scribe_admin
Config file changes​
tip
php artisan scribe:upgrade
automatically handles all the changes in this section.
- A new
examples
key has been added, to configure how Scribe generates examples. It comes with two keys:faker_seed
(the old top-levelfaker_seed
was moved here)models_source
, for configuring how Scribe generates example models for API resources and transformers. See the docs for usage.
- A new
groups
key has been added. It comes with two items:default
(the olddefault_group
was moved here)order
, where you can order your groups, subgroups and endpoints. See the docs for usage.
Endpoints sorting​
tip
php artisan scribe:upgrade
automatically handles all the changes in this section.
In the past, the only way to sort your endpoints was by naming them in alphabetical order (eg "1. Users", "2. Tasks"), or reordering them in the generated YAML files. The first approach makes your documentation ugly, the second isn't very scalable. Scribe v4 brings a simpler approach: list the groups and endpoints in the groups.order
config item, in the order you want them in.
Because of this, we've dropped support for the previous editing/renaming files approach, as well as beforeGroup
and afterGroup
on custom endpoints. Migrating is simple: when you run scribe:upgrade
, it will automatically import the existing order of your groups into the groups.order
key.
Plugin API​
If you've written custom strategies, the class interface has changed a tiny bit.
The
$routeRules
parameter of__invoke()
is now optional. This means you should replacearray $routeRules
witharray $routeRules = []
public function __invoke(
ExtractedEndpointData $endpointData,
- array $routeRules
+ array $routeRules = []
): ?arrayThere's a new instance property,
public ?ExtractedEndpointData $endpointData;
. You can add this anywhere in your class. It's not used for anything, and it's not set in the constructor, so you can ignore it, but it's a handy container to set/retrieve the endpoint being processed without having to pass it around.
Blade templates​
(For those who published and customized the themes' templates)
No major changes, but three things to note:
- Because of the addition of subgroups, we had to make some changes to the
groups.blade.php
file. - We moved the logic that generates headings for the
sidebar.blade.php
into agetHeadings
method in theHtmlWriter
class. - We changed response fields so they can expand/collapse like body parameters. To do this, we:
- added a
nestedResponseFields
property to theOutputEndpointData
class. - renamed
body-parameters.blade.php
tonested-fields.blad.php
, and renamed theparameters
input parameter tofields
. Here's the commit.
- added a
If you're affected by these changes, we recommend you copy the new files from the project's repo, and make any changes you had (they're fairly small files).
Attributes​
To enable PHP 8 attributes, you'll need to manually add the needed strategies to your config file:
'strategies' => [
'metadata' => [
Strategies\Metadata\GetFromDocBlocks::class,
+ Strategies\Metadata\GetFromMetadataAttributes::class,
],
'urlParameters' => [
Strategies\UrlParameters\GetFromLaravelAPI::class,
Strategies\UrlParameters\GetFromLumenAPI::class,
+ Strategies\UrlParameters\GetFromUrlParamAttribute::class,
Strategies\UrlParameters\GetFromUrlParamTag::class,
],
'queryParameters' => [
Strategies\QueryParameters\GetFromFormRequest::class,
Strategies\QueryParameters\GetFromInlineValidator::class,
+ Strategies\QueryParameters\GetFromQueryParamAttribute::class,
Strategies\QueryParameters\GetFromQueryParamTag::class,
],
'headers' => [
Strategies\Headers\GetFromRouteRules::class,
+ Strategies\Headers\GetFromHeaderAttribute::class,
Strategies\Headers\GetFromHeaderTag::class,
],
'bodyParameters' => [
Strategies\BodyParameters\GetFromFormRequest::class,
Strategies\BodyParameters\GetFromInlineValidator::class,
+ Strategies\BodyParameters\GetFromBodyParamAttribute::class,
Strategies\BodyParameters\GetFromBodyParamTag::class,
],
'responses' => [
+ Strategies\Responses\UseResponseAttributes::class,
Strategies\Responses\UseTransformerTags::class,
Strategies\Responses\UseApiResourceTags::class,
Strategies\Responses\UseResponseTag::class,
Strategies\Responses\UseResponseFileTag::class,
Strategies\Responses\ResponseCalls::class,
],
'responseFields' => [
+ Strategies\ResponseFields\GetFromResponseFieldAttribute::class,
Strategies\ResponseFields\GetFromResponseFieldTag::class,
],
],
Finally, if you'd like to automatically replace (most of) your docblock tags with attributes (see the docs on annotations for advantages and disadvantages), you can also do that. We've provided a Rector rule to automatically convert certain tags to attributes.