Scribe tries to extract as much information about your API as it can from your code, but you can (and should) help it by providing more information.
By default (and in the examples here), Scribe extracts info from your controller/request handler. However, if you prefer an alternative approach, the third-party plugin Scribe-TDD allows Scribe to extract the documentation from your API tests instead.
For example, let's take a simple "healthcheck" endpoint:
From this, Scribe gets:
It's not much, but it's a good start. We've got a URL, example requests, and an example response. Plus, an API tester (Try It Out).
With a little more work, we can make this better:
We've added a title and description of the endpoint (first three lines). We've also added another example response, plus descriptions of some of the fields in the response.
Now, we get richer information:
Sure, our docblock is a bit noisier now, but that's not such a bad thing! In fact, you could say it's a good thing—the docs are next to the code, so:
- it's harder to forget to update them when you change the code
- a new dev can instantly see the docs and understand the endpoint's behaviour.
Scribe tries to keep docblocks human-readable, so they make sense to you, not just to the machine.
Apart from docblocks, Scribe supports some other ways to annotate your API. For example, you can provide general API information and defaults in your
config/scribe.php, add or edit YAML files containing the endpoint details (more on that here), or use custom strategies that read your code.
We'll demonstrate these in the next few sections.
You can exclude an endpoint from the documentation by using the
@hideFromAPIDocumentation tag in its docblock.