OpenAPI Express Viewer

A lightweight Express.js middleware for serving OpenAPI/Swagger documentation with both UI and raw spec endpoints.

Features

• Serve Swagger UI for interactive API documentation
• Serve raw OpenAPI specification in JSON and YAML formats
• Support for both file-based and object-based specifications
• TypeScript support out of the box

API documentation

Check the autogenerated documentation here.

Installation

npm install @map-colonies/openapi-express-viewer

Usage

Basic Example

import express from 'express';
import { OpenapiViewerRouter } from '@map-colonies/openapi-express-viewer';

const app = express();

const config = {
  filePathOrSpec: './openapi.yml', // Path to your OpenAPI spec file
  uiPath: '/api-docs',            // UI endpoint
  rawPath: '/spec'                // Raw spec endpoint
};

const openapiRouter = new OpenapiViewerRouter(config);
openapiRouter.setup();
app.use('/', openapiRouter.getRouter());

app.listen(3000);

Using Object Specification

import { OpenapiViewerRouter } from '@map-colonies/openapi-express-viewer';

const openapiSpec = {
  openapi: '3.0.0',
  info: {
    title: 'My API',
    version: '1.0.0'
  }
  // ... rest of your OpenAPI specification
};

const config = {
  filePathOrSpec: openapiSpec,
  uiPath: '/api-docs'
};

const openapiRouter = new OpenapiViewerRouter(config);
// ... rest of setup

Configuration Options

| Option | Type | Required | Description | |--------|------|----------|-------------| | filePathOrSpec | string \| object | Yes | Path to OpenAPI spec file or specification object | | uiPath | string | Yes | Endpoint path for Swagger UI | | rawPath | string | No | Endpoint path for raw specification files |

Endpoints

When configured with rawPath: '/spec', the following endpoints become available:

• GET /spec.json - Raw OpenAPI spec in JSON format
• GET /spec.yml - Raw OpenAPI spec in YAML format
• GET /spec.yaml - Raw OpenAPI spec in YAML format (alternative extension)
• GET /api-docs - Swagger UI interface (based on uiPath configuration)