Scribe for Node.js

Sep 07, 2021

Contents

1 Features 3

2 Contents 5 2.1 Getting Started...... 5 2.2 Documenting your API...... 12 2.3 Generating Documentation...... 29 2.4 Configuration...... 31 2.5 Customizing the generated documentation...... 34 2.6 Troubleshooting and Debugging...... 38

3 Supported frameworks 41

4 Usage 43 4.1 Adonis.js...... 43 4.2 Express...... 43 4.3 Restify...... 44

i ii Scribe for Node.js

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

Generate API documentation for humans from your Node.js codebase. Here’s what the output looks like. There’s a Laravel version, too!

Wondering where to start? Check out our getting started guide for your framework: Adonis.js 4, Express, and Restify,.

Tip: Scribe helps you generate docs automatically, but if you really want to make friendly, maintainable and testable API docs, there’s a few more things you need to know. So I made a course for you.

Contents 1 Scribe for Node.js

2 Contents CHAPTER 1

Features

• Pretty HTML documentation page, with included code samples and friendly text • Included “Try It Out” button so users can test endpoints right from their browser • Markdown source files that can be edited to modify docs • Safely calls API endpoints to generate sample responses, with authentication and other custom configuration supported • Supports Postman collection and OpenAPI (Swagger) spec generation

3 Scribe for Node.js

4 Chapter 1. Features CHAPTER 2

Contents

2.1 Getting Started

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

2.1.1 Getting Started with Scribe for Adonis.js

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

Install and configure

First, install the package: npm i @knuckleswtf/scribe-adonis

Then add the service provider to the aceProviders array in your start/app.js: const aceProviders=[ '@adonisjs/lucid/providers/MigrationsProvider', '@knuckleswtf/scribe-adonis/providers/ScribeProvider', // <-- Add this ]

Next, create your config file: node ace scribe:init

This will ask you a few questions and create a .scribe.config.js file in your project directory. There are a few other useful settings you should change in that file, but we’ll leave them as is for now.

5 Scribe for Node.js

Do a test run

Now let’s do a test run. Run the command to generate your docs.

node ace scribe:generate

Visit your newly generated docs. Find the docs/index.html file in your public/ folder and open it in your browser.

Tip: Your docs are always accessible by opening the public/docs/index.html file on your machine. However, when deployed, you’ll probably want to pass it through your Adonis app. To do that, you can either set up your own routing or uncomment/add Adonis/Middleware/Static, to the serverMiddleware array in start/kernel.js.

There’s also a Postman collection generated for you. You can get it by visiting public/docs/collection. json. The link will also be added to the sidebar of the webpage. If you’d like an OpenAPI (Swagger) spec, Scribe can do that too. Set openapi.enabled in your config to true, then run the generate command. You can get the generated spec by visiting public/docs/openapi.yaml. The link will also be added to the sidebar of the webpage. Great! You’ve seen what Scribe can do. Now, let’s refine our docs to match what we want.

Add general information about your API

Here are some things you can customise with Scribe: • The introductory text • Authentication information • Languages for the example requests • A logo to show in your docs. For details, check out Documenting API information.

Filter your routes

You might also want to decide what routes you want to document. By default, Scribe will try to document all of your routes (except websocket routes), so if you’re okay with that, you can leave it at that. If you’d like to exclude some routes, there are two ways: • In the docblock for the endpoint, add this tag: @hideFromApiDocs. • Set the routes key in your .scribe.config.js. Here’s what it looks like:

routes:[ { include:[' *'], exclude:[' *.websocket'], apply:{ headers:{ }, responseCalls:{ methods:['GET'], } (continues on next page)

6 Chapter 2. Contents Scribe for Node.js

(continued from previous page) } } ],

With Scribe, you split up your routes into route groups. Each entry in the routes array is a single group. The main purpose of these groups is so you can apply different settings to multiple endpoints in one go. For instance, for some routes, you’d like an Api-Version header to be added to some routes, but not others, you can easily configure that here. You can also configure response calls in here. By default, all your routes are in a single group, and we recommend leaving them like that. You can split your routes later if you realise you need to. Here’s the full documentation on configuring routes.

Add more information to your routes

Scribe tries to figure out information about your routes, but it needs more help from you to go far. Here’s some information you can enrich: • Groups (you can group your endpoints by domain eg “User management”, “Order information”) • URL parameters • Request Headers • Body parameters • Query parameters • Example responses • Fields in the response Check out how to do this in the guide on Documenting your API.

Generate and publish

After making changes as needed, you can run scribe:generate as many times as you want. When you’re happy with how your documentation looks, you’re good to go. You can add the generated documentation to your version control and deploy as normal, and your users will be able to access it as you’ve configured.

2.1.2 Getting Started with Scribe for Express

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

Install and configure

First, install the package: npm i @knuckleswtf/scribe-express

Next, create your config file:

2.1. Getting Started 7 Scribe for Node.js

npx scribe init

This will ask you a few questions and create a .scribe.config.js file in your project directory. There are a few other useful settings you should change in that file, but we’ll leave them as is for now.

Do a test run

Now let’s do a test run. You’ll need to locate your “app file” — the file where you create your main Express app and attach routes. Usually an index.js or app.js. Run the scribe generate command to generate your docs, passing in the path to your app file (for example, ./index.js).

npx scribe generate -a

# Example: # npx scribe generate -a app.js

Visit your newly generated docs. Find the docs/index.html file in your public/ folder and open it in your browser.

Tip: Your docs are always accessible by opening the public/docs/index.html file on your machine. However, when deployed, you’ll probably want to pass it through your Express app. To do that, you can either set up your own routing or make sure you’re using express.static() middleware.

There’s also a Postman collection generated for you. You can get it by visiting public/docs/collection. json. The link will also be added to the sidebar of the webpage. If you’d like an OpenAPI (Swagger) spec, Scribe can do that too. Set openapi.enabled in your config to true, then run the generate command. You can get the generated spec by visiting public/docs/openapi.yaml. The link will also be added to the sidebar of the webpage. Great! You’ve seen what Scribe can do. Now, let’s refine our docs to match what we want.

Add general information about your API

Here are some things you can customise with Scribe: • The introductory text • Authentication information • Languages for the example requests • A logo to show in your docs. For details, check out Documenting API information.

Filter your routes

You might also want to decide what routes you want to document. By default, Scribe will try to document all of your routes (except websocket routes), so if you’re okay with that, you can leave it at that. If you’d like to exclude some routes, there are two ways: • In the docblock for the endpoint, add this tag: @hideFromApiDocs.

8 Chapter 2. Contents Scribe for Node.js

Note: For Express routes, the docblock containing info for Scribe needs to be on the route declaration, not the function declaration. For instance: class UserController { /** * This won't work. * @hideFromApiDocs */ createUser(req, res) { } }

/** * This will work. * @hideFromApiDocs */ app.post('/users', UserController.createUser)

• Set the routes key in your .scribe.config.js. Here’s what it looks like:

routes:[ { include:[' *'], exclude:[' *.websocket'], apply:{ headers:{ }, responseCalls:{ methods:['GET'], } } } ],

With Scribe, you split up your routes into route groups. Each entry in the routes array is a single group. The main purpose of these groups is so you can apply different settings to multiple endpoints in one go. For instance, for some routes, you’d like an Api-Version header to be added to some routes, but not others, you can easily configure that here. You can also configure response calls in here. By default, all your routes are in a single group, and we recommend leaving them like that. You can split your routes later if you realise you need to. Here’s the full documentation on configuring routes.

Add more information to your routes

Scribe tries to figure out information about your routes, but it needs more help from you to go far. Here’s some information you can enrich: • Groups (you can group your endpoints by domain eg “User management”, “Order information”) • URL parameters • Request Headers • Body parameters

2.1. Getting Started 9 Scribe for Node.js

• Query parameters • Example responses • Fields in the response Check out how to do this in the guide on Documenting your API.

Generate and publish

After making changes as needed, you can run scribe generate as many times as you want. When you’re happy with how your documentation looks, you’re good to go. You can add the generated documentation to your version control and deploy as normal, and your users will be able to access it as you’ve configured.

2.1.3 Getting Started with Scribe for Restify

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

Install and configure

First, install the package:

npm i @knuckleswtf/scribe-restify

Next, create your config file:

npx scribe init

This will ask you a few questions and create a .scribe.config.js file in your project directory. There are a few other useful settings you should change in that file, but we’ll leave them as is for now.

Do a test run

Now let’s do a test run. You’ll need to locate your “server file” — the file where you set up and start your Restify server, usually an index.js or server.js. Run the scribe generate command to generate your docs, passing in the path to your server file (for example, ./index.js).

npx scribe generate -s

# Example: # npx scribe generate -s server.js

Visit your newly generated docs. Find the docs/index.html file in your public/ folder and open it in your browser.

Tip: Your docs are always accessible by opening the public/docs/index.html file on your machine. However, when deployed, you’ll probably want to pass it through your Restify app. To do that, you can either set up your own routing or use the serveStatic plugin.

10 Chapter 2. Contents Scribe for Node.js

There’s also a Postman collection generated for you. You can get it by visiting public/docs/collection. json. The link will also be added to the sidebar of the webpage. If you’d like an OpenAPI (Swagger) spec, Scribe can do that too. Set openapi.enabled in your config to true, then run the generate command. You can get the generated spec by visiting public/docs/openapi.yaml. The link will also be added to the sidebar of the webpage. Great! You’ve seen what Scribe can do. Now, let’s refine our docs to match what we want.

Add general information about your API

Here are some things you can customise with Scribe: • The introductory text • Authentication information • Languages for the example requests • A logo to show in your docs. For details, check out Documenting API information.

Filter your routes

You might also want to decide what routes you want to document. By default, Scribe will try to document all of your routes (except websocket routes), so if you’re okay with that, you can leave it at that. If you’d like to exclude some routes, there are two ways: • In the docblock for the route declaration, add this tag: @hideFromApiDocs.

Note: For Restify routes, the docblock containing info for Scribe needs to be on the route declaration, not the function declaration. For instance:

class UserController { /** * This won't work. * @hideFromApiDocs */ createUser(req, res) { } }

/** * This will work. * @hideFromApiDocs */ server.post('/users', UserController.createUser)

• Set the routes key in your .scribe.config.js. Here’s what it looks like:

routes:[ { include:[' *'], exclude:[' *.websocket'], apply:{ (continues on next page)

2.1. Getting Started 11 Scribe for Node.js

(continued from previous page) headers:{ }, responseCalls:{ methods:['GET'], } } } ],

With Scribe, you split up your routes into route groups. Each entry in the routes array is a single group. The main purpose of these groups is so you can apply different settings to multiple endpoints in one go. For instance, for some routes, you’d like an Api-Version header to be added to some routes, but not others, you can easily configure that here. You can also configure response calls in here. By default, all your routes are in a single group, and we recommend leaving them like that. You can split your routes later if you realise you need to. Here’s the full documentation on configuring routes.

Add more information to your routes

Scribe tries to figure out information about your routes, but it needs more help from you to go far. Here’s some information you can enrich: • Groups (you can group your endpoints by domain eg “User management”, “Order information”) • URL parameters • Request Headers • Body parameters • Query parameters • Example responses • Fields in the response Check out how to do this in the guide on Documenting your API.

Generate and publish

After making changes as needed, you can run scribe generate as many times as you want. When you’re happy with how your documentation looks, you’re good to go. You can add the generated documentation to your version control and deploy as normal, and your users will be able to access it as you’ve configured.

2.2 Documenting your API

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

Scribe tries to infer information about your API from your code, but you can enrich this information in the config and by using annotations (tags in doc block comments).

12 Chapter 2. Contents Scribe for Node.js

Important: For Express and Restify routes, the docblock needs to be on the route declaration, not the function declaration. For instance:

2.2.1 Adding general information about your API

Attention: These docs are for Scribe for JS v1, which is no longer maintained. See scribe.knuckles.wtf/nodejs for Scribe for JS v2.

Authentication information

You can add authentication information for your API using the auth section in .scribe.config.js.

Important: Scribe uses your specified authentication information in three places: • Generating an “Authentication” section in your docs • Adding authentication parameters to your example requests for endpoints marked as @authenticated (or if you have with auth.default = true) • Adding the necessary auth parameters with the specified value to response calls for endpoints marked as @authenticated (or if you have with auth.default = true)

Here’s how you’d configure auth with a query parameter named apiKey: module.exports={ // ... auth:{ enabled: true, in: 'query', name: 'apiKey', useValue: () => process.env.SCRIBE_API_KEY, placeholder: 'YOUR-API-KEY', extraInfo: 'You can retrieve your key by going to settings and clicking

˓→Generate API key.', }, // ... };

If apiKey were to be a body parameter, the config would be same. Just set in to 'body'. Here’s an example with a bearer token (also applies to basic auth, if you change in to 'basic'): module.exports={ // ... auth:{ enabled: true, in: 'bearer', name: 'hahaha', // <--- This value is ignored for bearer and basic auth useValue: () => process.env.SCRIBE_API_KEY, placeholder: '{ACCESS_TOKEN}', extraInfo: 'You can retrieve your token by visiting your dashboard and

˓→clicking Generate API token.', (continues on next page)

2.2. Documenting your API 13 Scribe for Node.js

(continued from previous page) }, // ... };

And here’s an example with a custom header:

module.exports={ // ... auth:{ enabled: true, in: 'header', name: 'Api-Key', // <--- The name of the header useValue: () => process.env.SCRIBE_API_KEY, placeholder: 'YOUR-API-KEY', extraInfo: 'You can retrieve your token by visiting your dashboard and

˓→clicking Generate API token.', }, // ... };

You can set whatever you want as the extraInfo. A good idea would be to tell your users where to get their auth key. The useValue field is only used by Scribe for response calls. It won’t be included in the generated output or exam- ples. You can specify a hardcoded value or a function that will be called during the response call. The 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.

Introductory text

The introText key in .scribe.config.js is where you can set the text shown to readers in the “Introduction” section. If your text is too long to be put in a config file, you can create a prepend.md containing the intro text and put it in the resources/docs folder.

Title

You can set the HTML