Read this page if you want a deeper understanding of how Scribe works (for instance, for the purpose of contributing).
When you run
scribe:generate for the first time#
Here's a high-level overview of what Scribe does on first run:
RouteMatcherclass to get the routes you want to document. The
RouteMatcherdoes this by fetching all your application's routes from the router (Laravel/Dingo) and filtering them based on your config.$routes = $routeMatcher->getRoutes($yourConfig);
Extractorprocesses each route and uses your configured strategies to extract info about it—metadata (eg name and description), parameters, and sample responses.$endpoints = $this->extractEndpointsInfoFromLaravelApp($yourRoutes);
After that, the endpoints are grouped (based on their
@grouptags). The grouping makes it easy for Scribe to loop over them and generate the output.$groupedEndpoints = Camel::groupEndpoints($endpoints);
The grouped endpoints are written to a bunch of YAML files, in a
.scribe/endpointsdirectory in your app. We don't need them right now, but we'll come back to those files later. See What are those YAML files for?
Alright, the extraction phase is done. Over to output.
When it's time for output, we call the
Writerclass, and pass in those grouped endpoints. It uses a couple of Blade templates to generate the HTML output.
Finally, the writer copies the generated HTMl, plus the included CSS and JS to your configured
public/docs), and your docs are ready!
If you enabled Postman or OpenAPI generation, the writer will also generate those. If you chose
laravel-type docs, the writer will convert the generated HTMl back into Blade files, and move them into the
On subsequent runs, the same thing happens. The only difference is that Scribe first checks to see if there are any YAML files present. If there are, it merges whatever it finds there with what it can extract from your endpoints.
Now, about those YAML files...
Earlier, we said that the grouped endpoints are written to some YAML files, in a
.scribe/endpoints directory in your app. Each group of endpoints goes into one file, and looks like this:
Internally, we call these Camel files, and they're very useful! They're intermediate output, which means they let you modify the data Scribe has extracted, before Scribe goes on to convert to HTML. This means:
- You can edit an endpoint's details. For instance, if Scribe made a mistake, or wasn't able to figure out some data, you can just find the YAML file and edit it. Then when you run
scribe:generateagain, Scribe will use your changes instead of what it figured out.
You can run
php artisan scribe:generate --no-extraction for Scribe to completely skip the extraction step and just use the YAML files.
You can sort your endpoints. If you want one endpoint to appear before another, just edit the
endpointskey in the YAML and arrange them how you prefer.
You can also sort groups. You'll notice the example above is
0.yaml. To sort groups, just rename the files how you wish, since it's one group per file. For instance, if I rename this file to
1.yaml, and another file to
0.yaml, that group will appear before this one in the docs.
You can add new endpoints. This is useful if you're using a package that adds extra routes (like Laravel Passport), and you want to document those. Custom endpoint files use a slightly different format from regular endpoints, so Scribe automatically adds an example
custom.0.yamlfile to the
.scribe/endpointsfolder, and you can edit it to add additional endpoints.
.scribe folder contains intermediate output—information about your API that Scribe has extracted.
endpointsfolder holds the endpoints information as YAML files. You can edit them to add/overwrite endpoints.
endpoints.cachefolder also holds endpoints information, but these files are not meant to be edited by the user. Scribe uses the files here to figure out when you've edited something in
intro.mdfiles contain the generated text for the "Authentication" and "Introduction" section of your docs. You can edit these.
.filehashesfile is how Scribe keeps track of changes you make to
Scribe regenerates the
.scribe folder on every run, while preserving any changes you've made to endpoints or Markdown files. Special cases:
- When you specify
--no-extraction, Scribe will not go through an extraction phase or regenerate the folder. Instead, it will use the information here to generate the output (HTML, Postman, OpenAPI).
- When you specify
--force, Scribe will overwrite your changes to this folder.