You can add basics such as the title, introductory text, base URL and authentication information in your
.scribe.config.js config file.
To set the HTML
<title> for the generated docs, use the
title key. This title will also be used in the Postman collection and OpenAPI spec.
You can add a description of your API using the
description key. This description will be displayed in the docs' "Introduction" section, and in the Postman collection and OpenAPI spec.
introText key is where you'll set the text shown in the "Introduction" section of your docs (after the
You can also edit the
.scribe/intro.md file that is added to your app after running
Markdown and HTML are also supported (see HTML helpers)
You can set the base URL to be displayed in your docs (also known as the display URL) with the
baseUrl key. For example, setting the
baseUrl to this:
http://sideprojects.knuckles.wtf will be shown in the generated docs, even if you ran the
generate command on localhost or in CI.
You can also set the URL used in the API tester (Try It Out) and for response calls with the
Maybe you've got a pretty logo for your API or company, and you'd like to display that on your documentation page. No worries! To add a logo, set the
logo key in
.scribe.config.js to the path of the logo. Here are your options:
To point to an image on an external public URL, set
logoto that URL.logo: 'http://your-company/logo.png',
To point to an image in your codebase, pass in the path to the image relative to your
outputPathdirectory (by default,
For example, if your logo is in
If you don't want a logo, set
You can add authentication information for your API using the
auth section in
You can also edit the
.scribe/auth.md file that is added to your app after running
Scribe uses the auth information you specify for four things:
- Generating an "Authentication" section in your docs
- Adding auth information to the Postman collection and OpenAPI spec
- Adding authentication parameters to your example requests for endpoints that use authentication
- Adding the necessary auth parameters with the specified value to response calls for endpoints that use authentication
Here's how you'd configure auth with a query parameter named
apiKey were to be a body parameter, the config would be same. Just set
Here's an example with a bearer token (also applies to basic auth, if you change
And here's an example with a custom header:
default field is the default behaviour of our API. If your endpoints are authenticated by default, set this to
true, then use
@unauthenticated on the method doc block if you need to turn off auth for specific endpoints. If your endpoints are open by default, leave this as
false, then use
@authenticated on the method doc block if you need to turn on auth for specific endpoints.
You can set whatever you want as the
extraInfo. A good idea would be to tell your users where to get their auth key.
useValue field is only used by Scribe for response calls. It won't be included in the generated output or examples. You can set it to a static value, or a function to be called to fetch that value
placeholder is the opposite of
useValue. It will be used only as a placeholder in the generated example requests.
For more information, see the reference documentation on the auth section.