@hazeljs/swagger

OpenAPI 3.0 documents and Swagger UI for HazelJS: class-level @Swagger, method-level @ApiOperation, automatic operation stubs for undocumented routes, and a small runtime config API.

Installation

npm install @hazeljs/swagger @hazeljs/core

Quick start

1. Import the module and register your app root

import { HazelModule } from '@hazeljs/core';
import { SwaggerModule } from '@hazeljs/swagger';

@HazelModule({
  imports: [SwaggerModule],
  controllers: [
    /* ... */
  ],
})
export class AppModule {}

// After you create the app (e.g. where you bootstrap HazelApp):
SwaggerModule.setRootModule(AppModule);

2. Optional: document metadata, servers, auth, UI CDN, global prefix

SwaggerModule.configure({
  title: 'My API',
  description: 'Production API',
  version: '1.0.0',
  servers: [{ url: 'http://localhost:3000', description: 'Local' }],
  globalPrefix: '/api', // match app.setGlobalPrefix('/api') so paths and Swagger UI spec URL align
  securitySchemes: {
    bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
  },
  security: [{ bearer: [] }],
  swaggerUiCdnBase: 'https://unpkg.com/[email protected]',
});

// Replace all options (e.g. in tests):
SwaggerModule.configure({}, true);

3. Decorate controllers

import { Controller, Get, Post, Body } from '@hazeljs/core';
import { Swagger, ApiOperation } from '@hazeljs/swagger';

@Swagger({
  title: 'Users API',
  description: 'User operations',
  version: '1.0.0',
  tags: [{ name: 'users', description: 'Users' }],
})
@Controller({ path: '/users' })
export class UserController {
  @Get()
  @ApiOperation({
    summary: 'List users',
    responses: { '200': { description: 'OK' } },
  })
  list() {
    return [];
  }

  @Post()
  @ApiOperation({
    summary: 'Create user',
    requestBody: {
      required: true,
      content: { 'application/json': { schema: { type: 'object' } } },
    },
    responses: { '201': { description: 'Created' } },
  })
  create(@Body() body: unknown) {
    return body;
  }
}

Routes without @ApiOperation still appear in the spec when autoGenerateOperations is true (default): summaries and placeholder request bodies are inferred from HTTP method and handler name. Set autoGenerateOperations: false in SwaggerModule.configure or pass { autoGenerateOperations: false } to SwaggerService.generateSpec to disable that for programmatic builds.

4. Open the UI and raw spec

• Swagger UI: GET /swagger/ (or GET {globalPrefix}/swagger/ if configured)
• OpenAPI JSON: GET /swagger/spec

Programmatic export (CI / codegen)

import { createOpenApiDocument } from '@hazeljs/swagger';
import { AppModule } from './app.module';
import * as fs from 'node:fs';

const doc = createOpenApiDocument(AppModule, {
  title: 'My API',
  version: '1.0.0',
  globalPrefix: '/api',
});
fs.writeFileSync('openapi.json', JSON.stringify(doc, null, 2));

YAML is not built in; pipe JSON through your preferred YAML tool if needed.

API reference

| Export | Role | | ----------------------- | --------------------------------------------------------------------------- | | SwaggerModule | Nest-style module; setRootModule, configure, getOptions | | SwaggerService | generateAutoSpec(module, options?), generateSpec(controllers, options?) | | createOpenApiDocument | Stateless helper around generateAutoSpec | | @Swagger | Class-level OpenAPI info / default tags | | @ApiOperation | Per-route operation (summary, parameters, requestBody, responses) |

Default components include Error and ValidationError schemas. Auto-generated error responses reference #/components/schemas/Error.

Roadmap / not implemented

The following are not in this package today (do not rely on READMEs or examples that mention Nest’s full @nestjs/swagger surface):

• @ApiTags, @ApiResponse, @ApiProperty, @ApiParam, @ApiQuery, @ApiBody, @ApiHeader, @ApiBearerAuth, @ApiSecurity as separate decorators
• DTO / class reflection for schemas
• Built-in YAML export or SwaggerModule.forRoot static module factory

Contributions welcome for any of the above.

Testing

npm test

License

Apache 2.0 © HazelJS