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
Copy

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);
Copy

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
Copy

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)