Skip to main content

ADR-0024: OpenAPI 3.0 for API Specification

Status​

Accepted - 2025-01-26

Context​

TVL Platform needs API documentation, client SDK generation, and contract testing for REST APIs.

Decision​

OpenAPI 3.0 (Swagger) as the API specification format, auto-generated from Fastify schemas.

Rationale​

  1. Auto-Generation: Generate from Fastify routes (single source of truth)
  2. Documentation: Interactive Swagger UI (try endpoints live)
  3. Client SDKs: Generate TypeScript, Python, Go clients
  4. Contract Testing: Validate requests/responses match spec
  5. Industry Standard: Most popular API spec format

Implementation​

// src/server.ts
import fastify from 'fastify';
import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUi from '@fastify/swagger-ui';

const app = fastify();

await app.register(fastifySwagger, {
  openapi: {
    info: {
      title: 'TVL Platform API',
      version: '1.0.0'
    },
    servers: [
      { url: 'https://api.tvl.com', description: 'Production' },
      { url: 'http://localhost:4000', description: 'Development' }
    ]
  }
});

await app.register(fastifySwaggerUi, {
  routePrefix: '/docs'
});

// Routes with schema
app.get('/bookings', {
  schema: {
    tags: ['Bookings'],
    summary: 'List all bookings',
    response: {
      200: {
        type: 'object',
        properties: {
          bookings: {
            type: 'array',
            items: { $ref: 'Booking#' }
          }
        }
      }
    }
  }
}, async (req, reply) => { ... });

// Start server
await app.listen({ port: 4000 });
console.log('Swagger UI: http://localhost:4000/docs');

Benefits​

  • ✅ Auto-Generated: From Fastify schemas (no manual YAML)
  • ✅ Interactive Docs: Swagger UI for testing
  • ✅ Client SDKs: Generate with openapi-generator
  • ✅ Validation: Ensure requests match spec
  • ✅ Postman: Import OpenAPI spec to Postman

References​