After you've documented your API, you can generate the docs using the
scribe:generate Artisan command.
php artisan scribe:generate
- extract information about your API and endpoints
- transform the extracted information into a HTML docs webpage (+ Postman collection and OpenAPI spec, if enabled)
- store the extracted API details in some YAML files (in
.scribe/endpoints), so you can manually edit them later
If you're using
static type, your docs (
index.html, CSS and JS files) will be generated to the
If you're using
- the Blade view will be at
- the CSS and JS assets will be in
- the Postman collection and OpenAPI spec will be in
If you're using
laravel type, you may need to exclude
storage/app/scribe/ from the gitignore (
storage/app/.gitignore), as it is ignored by default (meaning your Postman/OpenAPI docs won't be committed). You can add this line to your .gitignore to achieve that:
For more details on what happens when you run
generate, see How Scribe Works.
Viewing the docs
To access your generated docs, start your Laravel app (
php artisan serve on local), then visit the path you configured (in
laravel.docs_url). By default, this would be
<your app url>/docs. This works for both types of docs.
If you're using
static type, you can also open the
public/docs/index.html locally in your browser.
Customising the environment
You can pass the
--env option to run this command with a specific env file. For instance, if you have a
.env.docs file, running
php artisan scribe:generate --env docs
will make Laravel load the
This is a handy way to customise the behaviour of your app for documentation purposes—for example, you can disable things like notifications when response calls are running.
After you generate your docs, you should also have a
.scribe folder. This folder is the "intermediate" output; it holds information about your API that Scribe has extracted, allowing you to overwrite some things before Scribe converts to HTML. See Modifying the docs for details.
You can choose to commit this folder, or not. If you commit this folder, you can make edits to the info Scribe has extracted, and Scribe will respect them when generating your docs on any machine, local or server.
If you don't commit, you can't make any edits to what Scribe has extracted, so generating on a different machine might give different results. Of course, you can still use annotations and other strategies to customise the information that gets passed to Scribe.
If you commit the folder, and you generate docs on your server after doing a
git pull, you might get warnings from Git about your local changes being overwritten. In that case, you should use
git restore . to discard local changes before
git pull and
Generating multiple docs
You can generate multiple independent sets of docs with Scribe by using the
--config flag. Supposing you want to have two sets of docs, one for your public API endpoints, and one for the admin endpoints. To do this:
- Create a second config file. You can name it something like
scribe_admin.php. This file will contain the config for our admin API docs, while
scribe.phpwill retain the config for the public API docs.
- Update the config in the new file. Make sure to correctly set:
routes: Configure this so the only routes matched here are your admin endpoints
static.output_path: If you're using
statictype, set this to a different path from the one in your
scribe.phpso the docs don't overwrite each other.
laravel.assets_directory: If you're using
laraveltype, you can set this to a different path from the one in your
scribe.phpso the docs' assets don't overwrite each other. This only matters if you're using different assets (CSS, JS) for each set of docs.
- If you're using
laraveltype, add a route for your docs (see the note below).
php artisan scribe:generate --config scribe_admin(or whatever the name of your config file is).
The inbuilt Scribe routing (
laravel.docs_url and related settings) will not work for multiple docs. You'll need to add your own routes. You can customise the logic from the
routes/ folder in the package repo.
Running on CI/CD
You might want to generate your docs as part of your deployment process. Here are a few things to note:
You'll also want to set your URLs:
- the base URL, which will be displayed in the docs and examples. You can set this with the config item
base_url. You'll probably want to set this to your production URL.
- the Try It Out URL, which is the URL where the in-browser API tester's requests will go to. You can set this with the config item
try_it_out.base_url. You could set this to your production or staging server.