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

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

Usage

$3

`typescript
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);
`

$3

`typescript
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 |

$3

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)