@cinnabun/openapi

Auto-generate OpenAPI 3.1 specs and Swagger UI for Cinnabun applications.

Installation

bun add @cinnabun/openapi

Quick Start

import { CinnabunApp, CinnabunFactory } from "@cinnabun/core";
import { OpenApiModule } from "@cinnabun/openapi";

@CinnabunApp({
  port: 3000,
  scanPaths: [],
  imports: [
    OpenApiModule.forRoot({
      title: "My API",
      version: "1.0.0",
      docsPath: "/api-docs",
      jsonPath: "/api-docs/json",
    }),
  ],
})
class App {}

CinnabunFactory.run(App);

Access Swagger UI at http://localhost:3000/api-docs and the JSON spec at http://localhost:3000/api-docs/json.

Decorators

Annotate controllers and DTOs for richer documentation:

import { RestController, GetMapping, PostMapping, Body } from "@cinnabun/core";
import { ApiTags, ApiOperation, ApiResponse, ApiProperty } from "@cinnabun/openapi";

@ApiTags("Users")
@RestController("/api/users")
class UserController {
  @GetMapping("/")
  @ApiOperation({ summary: "List all users" })
  @ApiResponse({ status: 200, description: "User list" })
  findAll() {
    return [];
  }

  @PostMapping("/")
  @ApiOperation({ summary: "Create user" })
  @ApiResponse({ status: 201, description: "Created" })
  create(@Body() body: CreateUserDto) {
    return body;
  }
}

class CreateUserDto {
  @ApiProperty()
  name!: string;

  @ApiProperty()
  email!: string;
}

Configuration

interface OpenApiModuleOptions {
  title?: string;
  version?: string;
  description?: string;
  docsPath?: string;   // default: "/api-docs"
  jsonPath?: string;  // default: "/api-docs/json"
}

License

MIT