platform-openapi

Multi-tenant Swagger/OpenAPI documentation system with feature-scoped discovery, customizable themes, and automatic endpoint registration.

Package: @breadstone/archipel-platform-openapi

Quick Start

import { Module } from '@nestjs/common';
import { SwaggerFeature, Api } from '@breadstone/archipel-platform-openapi';

@SwaggerFeature({
  name: 'User Management',
  description: 'User CRUD and profile operations',
  version: '1.0',
})
@Controller('api/v1/users')
export class UserController {
  @Api({
    summary: 'Get user by ID',
    responses: { 200: { description: 'User found' } },
  })
  @Get(':id')
  public async getUser(@Param('id') id: string): Promise<UserResponse> {
    // ...
  }
}

---

Feature-Scoped Documentation

The key concept is per-feature Swagger documents — each feature or module gets its own Swagger UI page, so teams can work independently without cluttering a single monolithic spec.

@SwaggerFeature Decorator

Associates a controller with a named feature group:

import { SwaggerFeature } from '@breadstone/archipel-platform-openapi';

@SwaggerFeature({
  name: 'Orders',
  description: 'Order management and fulfillment',
  version: '2.0',
  tags: ['orders', 'fulfillment'],
})
@Controller('api/v1/orders')
export class OrderController {
  /* ... */
}

@Api Decorator

Enriches individual endpoints with OpenAPI metadata:

import { Api } from '@breadstone/archipel-platform-openapi';

@Api({
    summary: 'Create a new order',
    description: 'Creates an order and initiates payment processing.',
    responses: {
        201: { description: 'Order created successfully' },
        400: { description: 'Invalid order data' },
        402: { description: 'Payment required' },
    },
})
@Post()
public async createOrder(@Body() body: CreateOrderDto): Promise<OrderResponse> { /* ... */ }

---

Multi-Document Service

Generate separate Swagger documents per feature:

import { SwaggerMultiDocumentService } from '@breadstone/archipel-platform-openapi';

@Injectable()
export class DocsController {
  constructor(private readonly _swaggerDocs: SwaggerMultiDocumentService) {}

  public generateAll(): Map<string, OpenAPIObject> {
    return this._swaggerDocs.generateAll();
    // Returns a map: 'User Management' → OpenAPI spec, 'Orders' → OpenAPI spec, ...
  }
}

Bootstrap Setup

import { SwaggerModule } from '@nestjs/swagger';
import { SwaggerMultiDocumentService, SwaggerTheme } from '@breadstone/archipel-platform-openapi';

async function bootstrap(): Promise<void> {
  const app = await NestFactory.create(AppModule);
  const docsService = app.get(SwaggerMultiDocumentService);
  const documents = docsService.generateAll();

  for (const [featureName, spec] of documents) {
    const path = `docs/${featureName.toLowerCase().replace(/\s+/g, '-')}`;
    SwaggerModule.setup(path, app, spec, {
      customCss: SwaggerTheme.getDefaultCss(),
    });
  }

  await app.listen(3000);
}

---

Discovery & Registry

SwaggerFeatureDiscovery

Auto-discovers all @SwaggerFeature decorated controllers at bootstrap:

import { SwaggerFeatureDiscovery } from '@breadstone/archipel-platform-openapi';

const discovery = app.get(SwaggerFeatureDiscovery);
const features = discovery.discoverAll();
// → [{ name: 'User Management', controllers: [...] }, ...]

SwaggerFeatureRegistry

Programmatic registry for feature configurations:

import { SwaggerFeatureRegistry } from '@breadstone/archipel-platform-openapi';

const registry = app.get(SwaggerFeatureRegistry);
registry.register({
  name: 'Admin',
  description: 'Admin-only endpoints',
  version: '1.0',
  controllers: [AdminController],
});

---

Exports Summary

Export	Type	Description
Api	Decorator	OpenAPI endpoint metadata
SwaggerFeature	Decorator	Feature-scoped Swagger grouping
SwaggerFeatureDiscovery	Service	Auto-discover features
SwaggerFeatureRegistry	Service	Manage feature configs
SwaggerMultiDocumentService	Service	Generate per-feature specs
SwaggerTheme	Utility	Theme customization
IFeatureSwaggerConfig	Interface	Feature config shape