Start here

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.

For example, let's take a simple "healthcheck" endpoint in an Express app:

app.get('/healthcheck', (req, res) => {
    return res.json({
        status: 'up',
        services: {
            database: 'up',
            redis: 'up',
        },
    });
});

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:

/**
 * Healthcheck
 *
 * Check that the service is up. If everything is okay, you'll get a 200 OK response.
 *
 * Otherwise, the request will fail with a 400 error, and a response listing the failed services.
 *
 * @response 400 scenario="Service is unhealthy" {"status": "down", "services": {"database": "up", "redis": "down"}}
 * @responseField status The status of this API (`up` or `down`).
 * @responseField services Map of each downstream service and their status (`up` or `down`).
 */
app.get('/healthcheck', (req, res) => {
    return res.json({
        status: 'up',
        services: {
            database: 'up',
            redis: 'up',
        },
    });
});

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.

An important note about docblocks

With Express and Restify, docblocks must be added to the route definition, not the controller/handler function. For example:

class ApiController {
  /**
   * This won't work. ❌
   * @response {"success": true}
   */
  healthcheck(req, res) {
  }   
}

/**
 * This will work.
 * @response {"success": true}
 */
app.get('/home', PagesController.homePage);

This is due to a limitation in how JavaScript and these frameworks work—there's no way to access the docblock or trace the file where a function was declared without complicated heuristics.

Beyond docblocks

Apart from docblocks, Scribe supports some other ways to annotate your API. For example, you can provide general API information and defaults in your .scribe.config.js, 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.

tip

You can exclude an endpoint from the documentation by using the @hideFromApiDocs tag in its docblock.