jsdoc-to-openapi is a tool for Node.js-based RESTful API service developers to automate their documentation writing process from the start of their development process.
It parses JSDoc-like syntax into an OpenAPI Specification, a standardized way of describing RESTful APIs. By documenting your code with comments like the following,
/**
* Get an array of Todos.
* @event GET: /todos - getTodos
* @returns {Todo[]} 200 - An array of todos
* @returns {Error} 400 - Bad Request
*/
...you can generate interactive API documentation using tools such as Swagger UI that allow you to test out your endpoints without ever running a curl command.
const buildSpec = require('jsdoc-to-openapi');
const filesToRead = ['./routes.js', './models.js']
const config = {
title: 'My Todos API',
version: '1.0.0',
servers: [{
url: 'https://api.server.com',
description: 'My main web server'
}]
}
app.get('/docs', (req, res) => {
buildSpec(filesToRead, config)
.then(spec => res.json(spec))
.catch(console.error)
})
Every JSDoc block for defining routes should have at least:
An @event tag listing the request method, route path, and the name of the handler function to be called when the route is visited. Note the route path has an interpolated path variable.
* @event GET: /todos/{todoId} - getTodoById
Several @returns tags for each response type, listing the type of object being returned with each status code, and an optional description for each code.
* @returns {Todo} 200 - A Todo object
* @returns {Error} 400 - Bad Request
* @returns {Error} default
Depending on the type of request being made, @param tags may be used to define a request body, query string, or path parameter. See the following examples:
// For GET `/todos/{todoId}`
* @param {string} path.todoId
// For GET `/todos?size=10&completed=true`
// Note: the square brackets denote an optional param
* @param {number} query.size - Max amount to return
* @param {boolean} [query.completed] - Is it done?
// For POST `/todos` with a request body
* @param {Todo} body.Todo - A new Todo
Note the pattern: {Schema} paramType.ObjectName - ObjectDescription.
An optional @tags array may be specified for adding keywords that can be used to categorize various routes in the UI.
* @tags todos, tasks, stuff
Schemas also need to be described and parsed if referenced in your documentation (e.g. Todo and Error). Declaring a schema is as easy as adding a @typedef with several @property tags:
/**
* @typedef Todo
* @property {string} todoId
* @property {string[]} descriptions - What to do
* @property {boolean} [completed]
*/
buildSpec takes three arguments:
- An array of file paths
- A configuration object
- An options object
These files will be read and parsed one by one from left to right. Note that any repeated route paths will overwrite the previous document block!
const paths = ['./routes/user.js', './routes/todos.js']
For information on what fields are used in the configuration object, see the OpenAPI spec documentation. Note that servers is an array, meaning multiple servers can be specified.
const config = {
title: 'My Todos API',
version: '1.0.0',
description: 'This is my Todos API',
servers: [
{
url: 'https://dev.server.com',
description: 'Development server'
},
{
url: 'https://api.server.com',
description: 'Production server'
}
]
}
The options object has a few miscellaneous items to describe, with more to come in future releases. Note that servers shows up again, but this time each server object has an additional root key...
const options = {
termsOfService: 'https://www.server.com/terms',
contact: {
name: 'API Support',
url: 'http://www.server.com/support',
email: 'support@server.com'
},
license: {
name: 'Apache 2.0',
url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
},
servers: [
{
root: '/todos',
url: 'https://todos.server.com,
description: 'Separate Todos server'
}
]
}
This allows you to specify path-specific servers to use. The root field identifies any defined route path that starts with /todos and uses the provided server information. This means multiple services (i.e. microservices) can be tested and interacted with from one single generated API specification!
More information to come in the future. Please feel free to contact me if you have any questions about using this tool.