npm package: @flightdev/openapi
Description: OpenAPI schema generation for Flight Framework API routes - optional, non-imposing
Latest version: 2.0.2

# @flightdev/openapi

Generate OpenAPI 3.1 specifications from your Flight API routes. Optional, non-imposing - use it only if you need API documentation.

## Installation

```bash
npm install -D @flightdev/openapi
```

## Quick Start

### CLI Usage

```bash
# 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

```typescript
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:

```typescript
// 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);
}
```

```typescript
// 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:

```typescript
// src/routes/api/docs.ts
import { swaggerUI } from '@flightdev/openapi/swagger-ui';

export const GET = swaggerUI({
  specUrl: '/api/openapi.json',
  title: 'My API Docs',
});
```

```typescript
// 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

```typescript
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:

```yaml
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