Guides
Documenting routes with JSDoc
Annotate handlers with JSDoc — no defineRoute required.
DocTreen reads JSDoc from handler function source at runtime. Place the JSDoc block inside the handler function body (at the top):
app.get('/users/:id', function (req, res) {
/**
* @description Get a user by ID
* @param {string} query.fields Comma-separated fields to return
* @response {string} id
* @response {string} name
* @response {string} email
*/
res.json({ id: req.params.id, name: 'Alice', email: 'alice@example.com' });
});Supported JSDoc tags
| Tag | Description | Example |
|---|---|---|
@description | Route description | @description Get all users |
@param {type} body.name | Request body field | @param {string} body.email |
@param {type} query.name | Query parameter | @param {string} query.search |
@response {type} name | Response field | @response {string} id |
@returns {Type} | Full response type (schema ref) | @returns {User} |
@header Name - value | Request header | @header Authorization - Bearer <token> |
Optional fields
Wrap a field name in [brackets] to mark it optional:
/**
* @param {string} body.name
* @param {string} [body.bio] optional
* @param {number} [body.age] optional
*/Named schema references
Pair JSDoc with defineSchema to reference shared
shapes by name:
const { defineSchema, s } = require('doctreen');
defineSchema('User', s.object({
id: s.number(),
name: s.string(),
email: s.string(),
}));
app.get('/users', function (req, res) {
/**
* @description List all users
* @returns {User[]}
*/
res.json([]);
});