Overview¶
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.
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
Contents¶
- Getting Started
- Documenting your API
- Adding general information about your API
- Specifying metadata about an endpoint
- Documenting headers for endpoints
- Documenting query and URL parameters for an endpoint
- Documenting body and file parameters for an endpoint
- Documenting responses from an endpoint
- Excluding endpoints from the documentation
- Generating Documentation
- Configuration
- Customizing the generated documentation
- Manually modifying the documentation after generating
- Specifying content to be added to the beginning or end of the documentation
- Adding more example languages [coming soon]
- Customizing the code used in examples templates [coming soon]
- Changing the Markdown templates [coming soon]
- Changing the CSS styles
- Troubleshooting and Debugging
Supported frameworks¶
Currently, only Adonis.js 4, Express 4+ and Restify 8+ are supported.
Usage¶
Node.js 12.4.0 or higher is required.
Adonis.js¶
Install with:
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
]
To generate your docs, run the Ace command scribe:generate
:
node ace scribe:generate
See the Getting Started Guide for more.
Express¶
Install with:
npm i @knuckleswtf/scribe-express
To generate your docs, you’ll need to locate your “app file”. Then pass the path to Scribe:
npx scribe generate -a <your-app-file>.js
See the Getting Started Guide for more.
Restify¶
Install with:
npm i @knuckleswtf/scribe-restify
To generate your docs, you’ll need to locate your “server file”. Your server file is the file where you set up and start your Restify server. Then pass the path to Scribe:
npx scribe generate -s <your-server-file>.js
See the Getting Started Guide for more.