open-index/open-npm huggingface dataset:
npm package: @map-colonies/openapi-express-viewer
Description: A package for openapi ui middleware for express
Latest version: 5.0.0

# 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](https://mapcolonies.github.io/infra-packages/modules/_map-colonies_openapi-express-viewer.html).


## Installation

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

## Usage

### Basic Example

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

### Using Object Specification

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

### 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)