Migrating from mpociot/laravel-apidoc-generator to Scribe v1¶
There’s quite a few changes in Scribe, and this guide aims to show you the key parts you need to look out for so things don’t break. After migrating, you should also check out the list of new features.
This guide describes how to migrate to Scribe version 1. Scribe 2 is the current release, so you should follow the migration guide for that when you’re done with this.
- PHP version: 7.2.5+
- Laravel/Lumen version: 5.8+
Before you start¶
- Remove the old package and install the new one:
composer remove mpociot/laravel-apidoc-generator # For Laravel composer require --dev "knuckleswtf/scribe:^1.0.0" # For Lumen composer require "knuckleswtf/scribe:^1.0.0"
- Publish the new config file:
php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-config
At this point, you should have both apidoc.php and scribe.php in your config folder. This is good, so you can easily copy your old config over and delete when you’re done.
If you’ve modified your generated Blade views, you should also publish the new ones:
php artisan vendor:publish --provider="Knuckles\Scribe\ScribeServiceProvider" --tag=scribe-views
If you’ve modified the generated Markdown or added prepend/append files, you should copy them to a separate folder (not in
resources/docs). After generating the new docs, you’ll have to manually add your changes in.
After you’ve done all of the above, delete your
public/docs folders, to prevent any conflicts with the new ones we’ll generate. If you’re using
laravel type output, you can also delete
postman.namekey has been removed instead. Use the
titlekey, which will set both Postman collection name and the generated doc’s HTMl title.
laravel.autoloadkey is now
laravel.add_routes, and is
laravel.docs_urlkey is now
/docsby default (no longer
/doc). This means if you’re using
laraveldocs type, your docs will be at
/docs and /docs.json.
- The Markdown output is now a set of files, located in
resources/docs. The route files are located in
resources/docs/groupsand are split by groups (1 group per file).
rebuildcommand has been removed. Instead, if you want Scribe to skip the extraction phase and go straight to converting the existing Markdown to HTML, run
php artisan scribe:generate --no-extraction.
falseby default, so no logo spot will be shown. Also, if you specify a logo, it will no longer be copied to the docs folder. Rather, the path to be logo will be used as-is as the
<img>tag in the generated doc. This means that you must use a path that’s publicly accessible. For example, if your logo is in
'logo' => '../img/logo.png'for
statictype (output folder is
'logo' => 'img/logo.png'for
You can also use a URL instead.
It’s a new package with a different name, so a few things have changed. This section is especially important if you’ve written any custom strategies or extended any of the provided classes.
- Replace all occurrences of
- Replace all occurrences of
- For strategies, change the type of the
$methodargument to the
ReflectionFunctionAbstractto enable support for Closure routes. It’s a superclass of
ReflectionMethod, so every other thing should work fine.
- For each strategy, add a
public $stageproperty and set it to the name of the stage the strategy belongs to. If you have a constructor defined, remove the
$stageargument from it.
requestHeadersstage has been renamed to
- If you’ve published the views, you’ll note that they are now in a different format. See the documentation on customising the views to see how things are organised now.
That should be all. Head on to the list of new features to see what’s new. If you come across anything we’ve missed, please send in a PR!