Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
koaSwagger
✓ import { koaSwagger } from 'koa2-swagger-ui';
✗ const koaSwagger = require('koa2-swagger-ui');
The package primarily uses named exports. While CommonJS `require` can be used, the modern `import` syntax is preferred for ESM projects.
KoaSwaggerUiOptions
✓ import { KoaSwaggerUiOptions } from 'koa2-swagger-ui';
This is a TypeScript type interface for configuring the middleware. Use it for strong typing when defining options.
Router
✓ import Router from 'koa-router';
✗ const Router = require('koa-router');
This is an import for `koa-router`, an optional but common dependency when defining routes for `koa2-swagger-ui`.
Demonstrates how to integrate `koa2-swagger-ui` into a Koa application using `koa-router` and load an OpenAPI specification from a local YAML file, serving the interactive documentation.
import Koa from 'koa';
import Router from 'koa-router';
import { koaSwagger } from 'koa2-swagger-ui';
import yamljs from 'yamljs';
import fs from 'node:fs';
import path from 'node:path';
const app = new Koa();
const router = new Router();
// Define an OpenAPI spec (e.g., in YAML)
const openApiSpecPath = path.resolve(__dirname, 'openapi.yaml');
// For a real app, you'd generate this or load it from a stable source.
// Here we create a dummy one if it doesn't exist for the example to run.
if (!fs.existsSync(openApiSpecPath)) {
fs.writeFileSync(openApiSpecPath, `
openapi: 3.0.0
info:
title: Koa2 Swagger UI Example API
version: 1.0.0
paths:
/hello:
get:
summary: Greets the world
responses:
'200':
description: A simple greeting
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Hello, Koa!
`);
}
const spec = yamljs.load(openApiSpecPath);
// Serve the Swagger UI
router.get('/docs', koaSwagger({
routePrefix: false, // Disables the default /docs prefix for the UI
swaggerOptions: {
spec, // Provide the spec object directly
// Alternatively, for a remote spec: url: 'http://petstore.swagger.io/v2/swagger.json',
},
title: 'Koa API Documentation',
hideTopbar: true,
}));
// Add a simple API route for demonstration
router.get('/hello', (ctx) => {
ctx.body = { message: 'Hello, Koa!' };
});
app.use(router.routes()).use(router.allowedMethods());
const PORT = 3000;
app.listen(PORT, () => {
console.log(`Server running on http://localhost:${PORT}`);
console.log(`API Docs available at http://localhost:${PORT}/docs`);
console.log('Use CTRL+C to stop the server.');
});
// To run this:
// 1. npm install koa koa-router koa2-swagger-ui yamljs @types/koa @types/koa-router @types/yamljs typescript ts-node
// 2. Add "type": "module" to package.json
// 3. npx ts-node your-file.ts
// Then open http://localhost:3000/docs
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, stat './openapi.yaml'
The OpenAPI specification file (e.g., `openapi.yaml`) specified in the `spec` option was not found at the given path.
fixEnsure the path to your spec file is correct and absolute, or that the file exists relative to your current working directory when the application starts. Use `path.resolve(__dirname, 'your-spec.yaml')` for clarity.
TypeError: koaSwagger is not a function
Incorrect import syntax (e.g., using `require` with a named export, or attempting a default import when none exists) or missing package installation.
fixEnsure `koa2-swagger-ui` is installed and use `import { koaSwagger } from 'koa2-swagger-ui';` for ESM, or `const { koaSwagger } = require('koa2-swagger-ui');` for CommonJS if compatible. The `url` or `spec` option must be provided for Swagger UI configuration.
The `swaggerOptions` object passed to `koaSwagger` is missing either the `url` property pointing to a remote OpenAPI spec, or the `spec` property containing the OpenAPI definition object directly.
fixEnsure your `koaSwagger` configuration includes `swaggerOptions: { url: 'your-spec-url.json' }` or `swaggerOptions: { spec: yourSpecObject }`. TypeError: Cannot read properties of undefined (reading 'routes')
Incorrectly importing or initializing `koa-router` when attempting to use its methods.
fixEnsure you have `koa-router` installed (`npm install koa-router`) and correctly imported `import Router from 'koa-router';` then initialized `const router = new Router();` before using it with `app.use(router.routes())`.
Audit
Dependencies
@types/koaoptionalPeer dependency required for TypeScript users to correctly type Koa applications when using this middleware.
koarequiredImplicit runtime dependency as this is a Koa middleware. Koa must be installed in your project.
koa-routeroptionalOptional dependency for more complex routing setups, often used in conjunction with this middleware, as shown in examples.
yamljsoptionalOptional dependency required for loading OpenAPI specifications from YAML files.