🧾 Xodocs

Xodocs is a developer-first tool that generates clean, human-readable OpenAPI documentation for your Express backend application using Zod and Swagger under the hood.

It simplifies the documentation process by reducing the amount of boilerplate comments required, promoting schema reusability, and keeping your API definitions tightly coupled to your code — not scattered across YAML files or verbose decorators.

---

🚨 The Problem

Swagger has become the de facto standard for documenting APIs, but maintaining Swagger annotations in complex projects often turns into a mess:

- Annotating every route with verbose comments or decorators
- Duplicating schema definitions across files
- Managing large Swagger configuration files manually
- Constantly syncing code and documentation

These issues lead to bloated, error-prone documentation that is painful to maintain.

---

✅ The Solution: Xodocs

Xodocs solves this by providing a clean, code-first documentation experience for Express applications.

✨ Key features:

- ✍️ Use minimal, structured JSDoc-style route annotations
- 🧠 Automatically detects routes and methods
- 🔗 Seamlessly integrates with zod-openapi
- 🔐 Simple authentication configuration
- 📚 Zero boilerplate OpenAPI generation
- 📂 Keeps your documentation and code in sync

---

🚀 Getting Started

$3

Install xodocs along with its peer dependency zod-openapi:

``bash
npm install xodocs zod zod-openapi
`

or with yarn:

`bash
yarn add xodocs zod zod-openapi
`

---

$3

At the entry point of your Express app (e.g., index.ts or server.ts):

`ts
import 'zod-openapi/extend';
`

This ensures that all Zod schemas are extended with the OpenAPI capabilities provided by zod-openapi.

$3

`ts
import express from 'express';
import { generateOpenAPIDocs } from 'xodocs';
import { AuthResponse, UserParamsId } from './schemas';

const app = express();

generateOpenAPIDocs(app, {
info: {
title: 'Xodocs Sample',
description: 'This is the official API of "Xodocs Sample"',
},
schemas: {
AuthResponse,
UserParamsId,
},
auth: {
type: 'bearer',
in: 'header',
scheme: 'token',
},
baseURL: 'http://localhost:3000',
});
`

$3

$3

| Property | Type | Description |
| ---------- | ------------------------- | -------------------------------------------------------------- |
| info | Partial | OpenAPI info object (e.g., title, version, description) |
| docsPath | Partial | Override default UI/JSON documentation routes |
| auth | AuthConfig | Optional global authentication configuration |
| baseURL | string | Optional base URL of the express app. |
| schemas | Record | Zod schemas used in route annotations (@response, @params) |

---

$3

| Property | Type | Description | Default |
| -------- | -------- | -------------------------------- | ---------------------- |
| ui | string | Route where Swagger UI is served | "/docs" |
| json | string | Route for raw OpenAPI JSON | "/docs/openapi.json" |

---

$3

| Property | Type | Description | Notes |
| ------------- | ------------------------ | ------------------------------------------------------ | --------------------- |
| type | "bearer" \| "apiKey" | Type of authentication | Required |
| name | string | Name of the header/query param (for apiKey) | Required for apiKey |
| in | "header" \| "query" | Location of the apiKey parameter | Required for apiKey |
| scheme | string | Auth scheme (defaults to "bearer" for bearer auth) | Optional |
| description | string | Description of the auth mechanism | Optional |

---

✍️ Annotating Controllers

Here's how you define routes with clean top-of-function comments:

`ts
export class AuthController {
// @public
// @route POST /login
// @summary Login a user
// @response 200: AuthResponse
// @tags Auth
static login = (_: any, res: any) => {
res.json({ token: 'abc123' });
};

// @route GET /user/{id}
// @summary Get user details
// @response 200: AuthResponse
// @params UserParamsId
// @tags Users
static user = (_: any, res: any) => {
res.json({ token: 'abc123' });
};
}
`

🧠 Xodocs will automatically read these annotations, match the method name, and link the referenced schemas from the config.

---

📦 Schema Definitions (Zod + OpenAPI)

Using zod-openapi, your schemas should be defined like this:

`ts
import { z } from 'zod';

// Request Body Schema
export const AuthResponse = z.object({
token: z.string().openapi({
description: 'JWT token returned after successful login',
example: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
}),
});

// Paramter Schema
export const UserParamsId = z.object({
id: z
.string()
.uuid()
.openapi({
param: {
name: 'id',
in: 'path',
},
example: 'f8b50a58-23f5-4f20-a08b-53f233e704a1',
description: 'The UUID of the user',
}),
page: z
.number()
.int()
.openapi({
param: {
name: 'page',
in: 'query',
},
example: 25,
description: 'Page',
}),
});
`

---

🌐 Output

Once configured, Xodocs generates:

- A beautiful Swagger UI at /docs
- A raw OpenAPI JSON spec at /docs/openapi.json

These can be easily customized with the docsPath config option.

---

🔐 Auth Support

Configure authentication globally with the auth option:

`ts
auth: {
type: 'bearer',
in: 'header',
scheme: 'token',
description: 'JWT token authentication',
}
`

Xodocs will automatically include this security scheme in the spec and apply it to all routes except those marked with @public`.

---

🤝 Contributing

We welcome contributions!

- Found a bug?
- Have a feature idea?
- Want to help make Xodocs better?

👉 Contribute here

---

🧠 Why Xodocs?

Unlike traditional Swagger tools that rely on bloated decorators or out-of-sync YAML files, Xodocs embraces:

- 📌 Simplicity
- 🧩 Zod-first validation and schema linking
- 🧼 Clean function-level documentation
- ⚙️ Automated generation with no runtime overhead

It’s the Swagger generation tool your Node.js projects actually deserve.

---

💡 License

MIT License © Elijah Soladoye