Migrating from mpociot/laravel-apidoc-generator to Scribe v3
Scribe is a successor to
mpociot/laravel-apidoc-generator, with a lot of improvements and changes. This guide aims to make migrating to Scribe easier and show you the key parts you need to look out for so things don't break.
The core documentation process remains largely the same. The major changes are in the config file and the advanced customization process.
- PHP version: 7.4+
- Laravel/Lumen version: 6+
Before you start
Follow the installation guide in the introduction.
Remove the old package:
composer remove mpociot/laravel-apidoc-generator
At this point, you should have both
scribe.php in your config folder. This is good, so you can easily compare and copy your old config over and delete when you're done.
_After you've done 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
Config file changes
postman.namekey has been removed. 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
requestHeadersstage in the
strategiesitem has been renamed to
Scribe no longer outputs Markdown as an intermediate step, but instead YAML. See details for how to work with them.
rebuildcommand has been removed. Instead, if you want Scribe to skip the extraction phase and go straight to converting the existing YAML to HTML, run
php artisan scribe:generate --no-extraction.
falseby default, so no logo spot will be shown in the docs.
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 docs. This means that you must use a URL or 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
If you've written any custom strategies, you should review Writing Plugins to see how plugins are written now.
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. If you come across anything we've missed, please send in a PR! We recommend reading through our docs to see all the improvements Scribe comes with.