Stop Writing OpenAPI Specs by Hand

#openapi #javascript #api #serverless

Writing API documentation sucks. You build an endpoint, then spend 20 minutes writing YAML that's outdated by your next commit.

What if your docs wrote themselves?

The Problem

OpenAPI/Swagger is great for API consumers. But maintaining specs manually means:

Duplicating schema definitions
Docs drifting out of sync with code
Tedious YAML editing for every endpoint

The Solution: Generate from Code

With Codehooks.io, define your schema once and get full OpenAPI 3.0 docs automatically:

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'])
});

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

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

export default app.init();

Deploy, then visit /docs — you get a fully interactive Swagger UI with all 8 CRUD endpoints documented.

Custom Routes? No Problem

For endpoints beyond CRUD, use the openapi() middleware:

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 });
  }
);

You can even pass Zod schemas directly — they auto-convert to JSON Schema:

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