Configuration¶
Attention
These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.
Here’s a rundown of what’s available in the .scribe.config.js
file.
Tip
If you aren’t sure what an option does, it’s best to leave it set to the default.
Output settings¶
outputPath
¶
Output folder. The HTML documentation, assets and Postman collection will be generated to this folder. Source Markdown will be in /docs
. Default: public/docs
.
baseUrl
¶
The base URL to be used in examples.
title
¶
The HTML <title>
for the generated documentation, and the name of the generated Postman collection.
description
¶
A description for the API. This will be used as the info.description
field in the Postman collection and OpenAPI spec, and placed as the first paragraph under the “Introduction” section in the doc webpage (before the introText
.
introText
¶
The text to place in the “Introduction” section. Markdown and HTML are supported.
interactive
¶
Set this to true
if you’d like Scribe to add a “Try It Out” button to your endpoints so users can test them from their browser. Default: true
.
..Important:: For “Try It Out” to work, you’ll need to make sure CORS is enabled on your endpoints
logo
¶
Path to an image file to use as your logo in the generated docs. This will be used as the value of the src attribute for the <img>
tag, so make sure it points to a public URL or path accessible from your web server. For best results, the image width should be 230px. Set this to false
if you’re not using a logo. Default: false
.
Note
This path will be used as-is in the HTML doc, so make sure it’s publicly accessible.
defaultGroup
¶
When documenting your api, you use @group
annotations to group API endpoints. Endpoints which do not have a group annotation will be grouped under the defaultGroup
. Defaults to "Endpoints"
.
exampleLanguages
¶
For each endpoint, an example request is shown in each of the languages specified in this array. Currently only bash
, and javascript
are supported. Default: ["bash", "javascript"]
postman
¶
Along with the HTML docs, Scribe can automatically generate a Postman collection for your endpoints. This section is where you can configure or disable that.
The collection will be created in <outputPath>/collection.json
.
enabled
: Whether to generate a Postman API collection. Default:true
overrides
: List of fields to apply to the generated collection. Dot notation is supported. For instance, if you’d like to override the version (in theinfo
object, you can setoverrides
to['info.version' => '2.0.0']
.
Extraction settings¶
auth
¶
Authentication information about your API. This information will be used:
- to derive the text in the “Authentication” section in the generated docs
- to add the auth headers/query parameters/body parameters to the docs and example requests
- to set the auth headers/query parameters/body parameters for response calls
Here are the available settings:
enabled
: Set this totrue
if your API requires authentication. Default:false
.in
: Where is the auth value meant to be sent in a request? Options:query
(for a query parameter)body
(for a body parameter)basic
(for HTTP Basic auth via an Authorization header)bearer
(for HTTP Bearer auth via an Authorization header)header
(for auth via a custom header)
name
: The name of the parameter (egtoken
,key
,apiKey
) or header (egAuthorization
,Api-Key
). Whenin
is set tobearer
orbasic
, this value will be ignored, and the header used will beAuthorization
.useValue
: The value of the parameter to be used by Scribe to authenticate response calls. You can also specify a function that will be called during the response call to provide the authentication value. This will not be included in the generated documentation. If this value is null or a function that returns null, Scribe will use a random value.placeholder
: Placeholder your users will see for the auth parameter in the example requests. If this is empty, Scribe will generate a realistic-looking auth token instead. Defaults to: “{YOUR_AUTH_KEY}”.extraInfo
: Any extra authentication-related info for your users. For instance, you can describe how to find or generate their auth credentials. Markdown and HTML are supported. This will be included in theAuthentication
section.
routes
¶
The routes
section is an array of items describing what routes in your application that should be included in the generated documentation.
Each item in the routes
array is a route group, an array containing rules defining what routes belong in that group, and what settings to apply to them.
include
: A list of patterns (route paths) which should be included in this group, even if they do not match the rules in thematch
section.exclude
: A list of patterns (route names or paths) which should be excluded from this group, even if they match the rules in thematch
section.
For instance, supposing our routes are set up like this:
app.get('/users', getUsers);
app.get('/users/{id}', getUserById);
app.get('ping', () => 'pong');
app.get('/admin', launchAdminApp);
If we want to match all routes but exclude the /admin
route, we could use this configuration:
routes: {
include: ['*'],
exclude: ['/admin'],
}
Or this:
routes: {
include: ['/users/*', '/ping'],
exclude: [],
}
Tip
You can use *
as a wildcard in domains, :code:`prefixes
, include
and exclude
. For instance, 'exclude' => ['users/*']
will exclude all routes with URLs starting with ‘users/’.
apply
: Theapply
section of the route group is where you specify any additional settings to be applied to those routes when generating documentation. There are a number of settings you can tweak here:headers
: Any headers you specify here will be added to the headers shown in the example requests in your documentation. They will also be included in response calls. Headers are specified as key => value strings.responseCalls
: These are the settings that will be applied when making “response calls”.
Tip
By splitting your routes into groups, you can apply different settings to different routes.
fakerSeed
¶
When generating example requests, Scribe uses the faker.js package to generate random values. If you would like the package to generate the same example values for parameters on each run, set fakerSeed
to any number (eg. 1234).
Tip
Alternatively, you can set example values for parameters when documenting them.