Stop Writing OpenAPI Specs by Hand

Source: Dev.to

The Problem with Manual OpenAPI Specs

Writing API documentation is tedious. After building an endpoint, you often spend minutes crafting YAML that quickly becomes outdated with the next code change. Maintaining specs by hand leads to:

• Duplicated schema definitions
• Docs drifting out of sync with the codebase
• Tedious YAML editing for every endpoint

Automatic OpenAPI Generation with Codehooks.io

Codehooks.io lets you define your schema once and automatically generates full OpenAPI 3.0 documentation.

Defining a Schema

import { app } from 'codehooks-js';
import { z } from 'zod';

const todoSchema = z.object({
  title: z.string().min(1).max(200),
  completed: z.boolean().default(false),
  priority: z.enum(['low', 'medium', 'high'])
});

Enabling OpenAPI & Swagger UI

// Enable OpenAPI + Swagger UI
app.openapi({
  info: { title: 'Todo API', version: '1.0.0' }
});

Auto‑Generating CRUD Endpoints

// Auto-generate CRUD endpoints
app.crudlify({ todos: todoSchema });

export default app.init();

Deploy the app and visit /docs to see a fully interactive Swagger UI with all CRUD endpoints documented.

Custom Endpoints with openapi() Middleware

For routes that go beyond basic CRUD, you can attach OpenAPI metadata directly.

import { app, openapi } from 'codehooks-js';

app.get(
  '/stats',
  openapi({
    summary: 'Get statistics',
    tags: ['Analytics'],
    responses: {
      200: { description: 'Stats retrieved' }
    }
  }),
  async (req, res) => {
    res.json({ total: 42 });
  }
);

Using Zod Schemas in Request Bodies

app.post(
  '/users',
  openapi({
    summary: 'Create user',
    requestBody: {
      content: {
        'application/json': { schema: UserSchema } // Zod schema auto‑converted
      }
    }
  }),
  handler
);

Supported Schema Formats

• Zod
• Yup
• JSON Schema

All are automatically converted to the appropriate OpenAPI definitions.

Key Features

• Swagger UI available at /docs (includes authentication support)
• Ability to filter endpoints and hide internal routes from public docs
• Zero duplication: a single schema serves both validation and documentation

Installation

npm install codehooks-js@latest

Getting Started

1. Add app.openapi() before app.crudlify().
2. Deploy with coho deploy.
3. Access your live documentation at /docs.

No more hand‑written YAML. No more drift. Just code.

Further Reading

Full documentation: