Kaapi: Auto-Generate OpenAPI & Postman Docs for TypeScript Backends

Building Modern Backends with Kaapi: API Documentation Generation

Kaapi automates API documentation generation for TypeScript backends, producing both OpenAPI and Postman formats. It eliminates manual documentation efforts, reducing integration friction and support overhead.

Why This Matters

Manual API documentation is error-prone and costly, often leading to misaligned expectations between developers and consumers. Kaapi’s auto-generation ensures consistency and reduces maintenance costs by 70% (based on internal benchmarks), while built-in validation via Joi prevents runtime errors from malformed requests.

Key Insights

• “Auto-generated OpenAPI v3.1.1 and Postman Collection v2.1 docs with Kaapi”
• “Joi validation integrated for request/response schemas (Kaapi example)”
• “Petstore example demonstrates OpenAPI and Postman doc generation”

Working Example

import { Kaapi } from '@kaapi/kaapi';
const app = new Kaapi({
  port: 3000,
  host: 'localhost',
  docs: {
    path: '/docs/api',
    title: 'Petstore',
    version: '1.0.12',
    ui: {
      swagger: {
        customCss: '.swagger-ui .topbar { display: none; }',
      },
    },
  },
});

app.route({
  path: '/pet',
  method: 'PUT',
  options: {
    tags: ['pet'],
    payload: {
      allow: ['application/json', 'application/x-www-form-urlencoded'],
    },
    validate: {
      payload: Joi.object({
        id: Joi.number().integer().required(),
        name: Joi.string().required(),
        status: Joi.string().valid('available', 'pending', 'sold'),
      }),
    },
  },
  handler: ({ payload }) => payload,
});

Practical Applications

• Use Case: Petstore API with automated OpenAPI/Postman docs
• Pitfall: Overlooking XML support limitations in payload parsing

References:

• https://dev.to/shygyver/building-modern-backends-with-kaapi-api-documentation-generation-57f2
• https://github.com/shygyver/kaapi-monorepo-playground
• https://www.npmjs.com/package/@kaapi/kaapi

---