@cvo/plugin-openapi

Automatic OpenAPI 3.0 (Swagger) specification generator for CVO Framework, derived from your Controllers and decorators.

🚀 Features

• Automatic Extraction: Infers routes, parameters, and metadata from @http, @Body, @Query, and @Path.
• Type Inference: Automatically generates JSON Schemas from TypeScript interfaces and classes.
• Dual Mode Support:
  • Runtime: Serves dynamic JSON via an endpoint (default: /api/openapi.json).
  • SSG: Generates static openapi.json during build for external documentation systems.

🛠 Configuration

Configure OpenAPI in your cvo.config.ts:

import { defineConfig } from '@cvo/core';

export default defineConfig({
  openapi: {
    title: 'My Project API',
    version: '1.0.0',
    description: 'Auto-generated API documentation',
    path: '/api/openapi.json' // Optional, defaults to /api/openapi.json
  }
});

🧠 Usage

In your server entry point, simply call server.setup(registry). The framework will automatically register the plugin based on your cvo.config.ts.

import { MonoServer, ApiRegistry } from '@cvo/server';

const server = new MonoServer();
const registry = server.getRegistry();

// ... register controllers ...

await server.setup(registry);
await server.listen();

Accessing the Spec

Once the server is running, you can access the JSON spec at: http://localhost:3000/api/openapi.json

📝 Decorator Support

The plugin automatically recognizes standard CVO decorators to build the specification:

• @http(method, path): Defines the endpoint route and HTTP verb.
• @Body(name?): Defines the request body. If a class is used as the type, it will be added to components/schemas.
• @Query(name?): Defines a URL query parameter.
• @Path(name?): Defines a URL path parameter (e.g., /users/:id).
• @Field: Required on class properties to include them in the OpenAPI Schema.

Example with Schemas

import { http, Body, Field } from '@cvo/core';

class CreateUserDto {
  @Field name: string;
  @Field age: number;
}

export class UserController {
  @http('POST', '/users')
  async create(@Body() data: CreateUserDto) {
    return { success: true };
  }
}

🚀 Static Generation (SSG)

To generate the spec file during build (e.g., in a CI/CD pipeline), use the generate method:

import { OpenApiPlugin } from '@cvo/plugin-openapi';
import { ApiRegistry } from '@cvo/server';

const registry = new ApiRegistry();
// ... register your controllers ...

const openapi = new OpenApiPlugin({
  title: 'My Static API',
  version: '1.0.0'
});

// Generates ./dist/api/openapi.json
openapi.generate(registry, './dist');