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:
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 <your-app-file>
# 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
.
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.
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.