OpenAPI Auto-Generation

SpaceNode can automatically generate an OpenAPI 3.0.3 specification from your modules, routes, and DTO schemas. Available at GET /openapi.json.

Enable

Set openapi: true for auto-generated spec with default settings:

// Minimal — just turn it on
const app = await createApp({
  openapi: true,
})

app.listen(3000)
// GET http://localhost:3000/openapi.json → full spec

Or pass a config object for custom metadata (this also enables OpenAPI):

const app = await createApp({
  openapi: {
    title: 'My Awesome API',
    version: '1.0.0',
    description: 'E-commerce backend API',
    servers: [
      { url: 'https://api.mysite.com', description: 'Production' },
      { url: 'http://localhost:3000', description: 'development' },
    ],
  },
})

What's Auto-Detected

• Paths & methods — from route definitions in modules
• Parameters — path params (:id) and query params
• Request body schemas — from DTO validation rules
• Tags — grouped by module name
• Auth — Bearer token security scheme detected from auth pipe

Route-Level Metadata

For richer docs, add OpenAPI metadata as the 5th tuple element:

routes: [
  ['GET', '/', 'list', [], {
    summary: 'List all products',
    description: 'Returns paginated product list',
    tags: ['products'],
  }],
  ['POST', '/', 'create', ['auth', 'dto:createDto'], {
    summary: 'Create a product',
    deprecated: false,
  }],
]

Query Parameters

Declare query parameters for GET routes using queryParams in the route metadata:

['GET', '/', 'list', [], {
  summary: 'List products',
  queryParams: [
    { name: 'q',     type: 'string',  description: 'Search query' },
    { name: 'page',  type: 'integer', description: 'Page number', required: false },
    { name: 'limit', type: 'integer', description: 'Items per page' },
  ],
}]

Each query param supports: name (required), type (default 'string'), required (default false), description.

Custom Responses

Override the auto-generated response schemas using responses:

['GET', '/:id', 'getById', [], {
  summary: 'Get product by ID',
  responses: {
    '200': { description: 'Product found' },
    '404': { description: 'Product not found' },
  },
}]

If you don’t provide responses, SpaceNode generates sensible defaults based on the HTTP method and whether a DTO is attached.

Module Tag Descriptions

Modules are grouped as tags in the OpenAPI spec. To add a tag description, set openapi.description in your module config:

// modules/products/module.js
export default {
  name: 'products',
  prefix: '/products',
  openapi: {
    description: 'Product catalog — CRUD operations and search',
  },
  routes: [...],
}