OpenAPI Generation from Code vs Code from OpenAPI

API documentation drifts from implementation. Hand-written OpenAPI specs go stale; generated specs are verbose and hard to customize.

Choose code-first or schema-first OpenAPI based on team workflow, then automate the link.

// Code-first with Fastify + @fastify/swagger
import Fastify from 'fastify';
import swagger from '@fastify/swagger';

const app = Fastify();
await app.register(swagger, {
  openapi: { info: { title: 'My API', version: '1.0.0' } },
});

app.get('/users/:id', {
  schema: {
    params: { type: 'object', properties: { id: { type: 'string' } } },
    response: {
      200: {
        type: 'object',
        properties: { id: { type: 'string' }, name: { type: 'string' } },
      },
    },
  },
}, async (req) => {
  return db.getUser(req.params.id);
});

// Schema-first with openapi-typescript
// npx openapi-typescript openapi.yaml -o src/types/api.d.ts
// Then use typed paths:
import type { paths } from './types/api';
type GetUserResponse = paths['/users/{id}']['get']['responses']['200']['content']['application/json'];

Code-first keeps types and docs in sync automatically. Schema-first enables design review before implementation and supports multi-language teams. Both approaches beat manual sync.