@flightdev/openapi

Generate OpenAPI 3.1 specifications from your Flight API routes. Optional, non-imposing - use it only if you need API documentation.

Installation

npm install -D @flightdev/openapi

Quick Start

CLI Usage

# Generate OpenAPI spec from your API routes
npx flight-openapi generate --routes src/routes --output openapi.yaml

# Generate JSON format
npx flight-openapi generate --routes src/routes --output openapi.json --format json

Programmatic Usage

import { generateOpenAPI } from '@flightdev/openapi';

const spec = await generateOpenAPI({
  routesDir: './src/routes',
  title: 'My API',
  version: '1.0.0',
  description: 'My awesome API',
});

console.log(JSON.stringify(spec, null, 2));

Documenting Routes

Add JSDoc comments to your API routes for richer documentation:

// src/routes/api/users.get.ts

/**
 * List all users
 * @tags Users
 * @summary Get all users with optional filtering
 * @param {string} [query.role] - Filter by role
 * @param {number} [query.limit=10] - Maximum results
 * @returns {200} List of users
 * @returns {401} Unauthorized
 */
export async function GET(ctx) {
  const users = await db.users.findMany();
  return Response.json(users);
}

// src/routes/api/users.post.ts

/**
 * Create a new user
 * @tags Users
 * @summary Create user account
 * @body {CreateUserInput} - User data
 * @returns {201} User created successfully
 * @returns {400} Invalid input
 */
export async function POST(ctx) {
  const body = await ctx.req.json();
  const user = await db.users.create({ data: body });
  return Response.json(user, { status: 201 });
}

Swagger UI Middleware

Serve Swagger UI for interactive API exploration:

// src/routes/api/docs.ts
import { swaggerUI } from '@flightdev/openapi/swagger-ui';

export const GET = swaggerUI({
  specUrl: '/api/openapi.json',
  title: 'My API Docs',
});

// src/routes/api/openapi.json.ts
import { generateOpenAPI } from '@flightdev/openapi';

export async function GET() {
  const spec = await generateOpenAPI({
    routesDir: './src/routes',
    title: 'My API',
    version: '1.0.0',
  });
  
  return Response.json(spec);
}

Configuration

interface GenerateOptions {
  /** Path to routes directory */
  routesDir: string;
  
  /** API title */
  title?: string;
  
  /** API version */
  version?: string;
  
  /** API description */
  description?: string;
  
  /** Server URLs */
  servers?: Array<{ url: string; description?: string }>;
  
  /** Include only API routes (default: true) */
  apiOnly?: boolean;
  
  /** Route prefix filter */
  prefix?: string;
}

Output

Generated OpenAPI 3.1 specification:

openapi: 3.1.0
info:
  title: My API
  version: 1.0.0
paths:
  /api/users:
    get:
      summary: Get all users
      tags: [Users]
      responses:
        '200':
          description: List of users
    post:
      summary: Create user account
      tags: [Users]
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserInput'
      responses:
        '201':
          description: User created successfully

License

MIT