api-document

Framework-agnostic API documentation UI with optional password protection.

• Works with Express, Fastify, Koa, Hono, or plain Node.js middleware style
• Reads endpoint schema from JSON files in your app
• Optional auth: if secret is not set, password page is bypassed

Install

npm i api-doc-ks

or

bun add api-doc-ks

Quick Start (Express)

import express from 'express';
import path from 'path';
import { createApiDoc } from 'api-doc-ks';

const app = express();

const apiDoc = createApiDoc({
  secret: process.env.API_DOCUMENT_SECRET,
  title: 'My App API',
  version: '1.0.0',
  schemaDir: path.resolve('./src/api-document'),
  basePath: '/api-doc',
});

app.use(express.urlencoded({ extended: false }));
app.use(express.json());

app.use(apiDoc);

app.listen(3000, () => {
  console.log('http://localhost:3000/api-doc');
});

API

initApiDocument(options)

createApiDoc(options)

Create middleware handler and initialize config in one step.

interface ApiDocumentConfig {
  secret?: string;
  title?: string;
  version?: string;
  schemaDir?: string;
  loadSchema?: () => Promise<{ endpoints?: unknown[]; errors?: Array<{ schemaPath: string; message: string }> }>;
  basePath?: string;
}

Options:

• secret optional password
• title document title shown in UI
• version document version shown in UI
• schemaDir path to schema directory in your app
  • default: src/api-document
• loadSchema custom loader function (if provided, schemaDir is ignored)
• basePath default mount path
  • default: /api-document

createApiDoc(options?: ApiDocumentConfig): Handler;

Auth Behavior

• If secret is set:
  • GET /<basePath> requires login
  • GET /<basePath>/data returns 401 when not authenticated
• If secret is not set or empty:
  • auth is disabled
  • password page is not shown
  • all api-doc routes are directly accessible

Routes

For basePath = /api-doc:

• GET /api-doc UI page
• POST /api-doc/login login endpoint
• POST /api-doc/logout logout endpoint
• GET /api-doc/script.js frontend script
• GET /api-doc/data schema JSON payload

Schema Directory

By default, library scans this directory in your app:

src/api-document

It reads all .json files recursively.

Example structure:

src/api-document
├── auth
│   └── login.json
└── users
    ├── get-users.json
    └── create-user.json

Schema JSON Example

{
  "name": "Get Users",
  "method": "GET",
  "path": "/api/users",
  "description": "Get user list",
  "request": {
    "headers": { "Authorization": "Bearer <token>" },
    "query": { "page": 1, "limit": 20 }
  },
  "response": {
    "status": "200",
    "data": [{ "id": "usr_01", "name": "John Doe" }]
  },
  "responseError": [
    { "code": "401", "message": "Unauthorized" }
  ]
}

TypeScript

Types are included in the package.

import { createApiDoc } from 'api-doc-ks';
import type { SchemaLoaderOptions, ApiDocumentData } from 'api-document/schema';

Backward Compatibility

• createApiDocumentHandler is still exported as an alias of createApiDoc.

Notes

• createApiDoc(...) returns a handler with its own captured config.
• Ensure your app can read the schema directory path you configure.