URL parameters

Scribe automatically extracts details about your URL parameters from your routes. It can figure out the names, required/optional status and sometimes the types of your parameters. However, you can overwrite this information or add new details, such as a description, using the @urlParam annotation.

tip

Scribe can figure out a few details about ID parameters in URLs. For example, if you have a route like /users/:id or /:user_id, Scribe will guess the parameter name (id/user_id) and description ("The ID of the user."). Of course, you can use @urlParam to override these.

The annotation takes the type of the parameter (within braces {}), its name, an optional "required" label, and an optional description. Valid types are string, integer, and number.

note

Remember, for Express and Restify, docblocks must go on the route definition.

For example, you can document an Express route like this: like this:

/**
 * @urlParam {integer} id required The ID of the post.
 * @urlParam {string} lang The language. Example: en
 */
app.get("/post/:id/:lang?", (req, res) => {...});

Scribe will generate a random example by default, but you can specify your own value in examples and response calls by ending the description with Example: <your-example>, as we did for the lang parameter above.

This gives:

If you want Scribe to omit a certain optional parameter (lang in our example) in examples and response calls, end the description with No-example. It will still be present in the docs.

/**
 * @urlParam {integer} id required The ID of the post.
 * @urlParam {string} lang The language. No-example
 */