Skip to main content

​
Overview

The Documentation class generates OpenAPI 3.1 specifications from your routing and configuration. 
import { Documentation } from "express-zod-api";

const documentation = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: "https://api.example.com",
});

const yaml = documentation.getSpecAsYaml();
const json = documentation.getSpec();

​
Configuration

​
routing
Routing
required
Your API routing object
​
config
Config
required
Your Express Zod API configuration
​
version
string
required
API version (semver)
​
title
string
required
API title
​
serverUrl
string | { url: string; description?: string }[]
required
Server URL(s)
​
description
string
API description
​
composition
'inline' | 'components'
Schema composition style
  • "inline": Schemas defined inline
  • "components": Schemas in separate components section with $ref
Default: "inline"
​
tags
Record<string, string | { description: string; url?: string }>
Tag descriptions for grouping endpoints

​
Methods

​
getSpec()

Returns OpenAPI specification as a JavaScript object. 
const spec = documentation.getSpec();
// Returns: OpenAPIObject

​
getSpecAsYaml()

Returns OpenAPI specification as YAML string. 
const yaml = documentation.getSpecAsYaml();
fs.writeFileSync("openapi.yaml", yaml);

​
Examples

​
Basic Documentation

import { Documentation } from "express-zod-api";

const docs = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: "https://api.example.com",
  description: "A sample API built with Express Zod API",
});

const yaml = docs.getSpecAsYaml();
fs.writeFileSync("docs/openapi.yaml", yaml);

​
Multiple Servers

const docs = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: [
    { url: "https://api.example.com", description: "Production" },
    { url: "https://staging-api.example.com", description: "Staging" },
    { url: "http://localhost:8090", description: "Development" },
  ],
});

​
With Tags

const docs = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: "https://api.example.com",
  tags: {
    users: "User management endpoints",
    posts: {
      description: "Blog post operations",
      url: "https://docs.example.com/posts",
    },
    admin: "Administrative functions",
  },
});

​
Component Composition

const docs = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: "https://api.example.com",
  composition: "components", // Use $ref for schemas
});

​
Serving with Swagger UI

import swaggerUi from "swagger-ui-express";
import { Documentation } from "express-zod-api";

const docs = new Documentation({
  routing,
  config,
  version: "1.0.0",
  title: "My API",
  serverUrl: "https://api.example.com",
});

const spec = docs.getSpec();

const config = createConfig({
  http: { listen: 8090 },
  cors: true,
  beforeRouting: ({ app }) => {
    app.use("/docs", swaggerUi.serve, swaggerUi.setup(spec));
  },
});

​
See Also

Documentation Guide

Complete documentation guide

OpenAPI

OpenAPI specification details

Tagging Endpoints

Organize endpoints with tags