OpenAPI & Swagger

@axeom/swagger is a core plugin that automatically generates OpenAPI 3.1.0 specifications from your route definitions and schemas. It also provides a beautiful, interactive documentation UI powered by Scalar.

Installation

npm install @axeom/swagger

Quick Start

Simply register the plugin on your Axeom instance. It will automatically scan all registered routes across your entire application.

import Axeom from '@axeom/framework';
import { swagger } from '@axeom/swagger';

const app = new Axeom()
  .use(swagger({
    info: {
      title: "Warehouse API",
      version: "2.4.0",
      description: "Managing industrial logic with gravity-free speed."
    }
  }));

app.listen(3000, () => {
  console.log("Swagger UI: http://localhost:3000/docs");
});

By default, your documentation will be available at:

• UI: /docs
• JSON Spec: /swagger.json

A high-fidelity technical readout provided by the Scalar integration.

Enriching your Documentation

Axeom's router is metadata-aware. You can add descriptions, summaries, and tags directly to your route definitions.

import { s } from '@axeom/framework';

app.post("/users", (ctx) => {
  return { id: 1, ...ctx.body };
}, {
  body: s.object({
    username: s.string(),
    email: s.string().email()
  }),
  summary: "Create a new user",
  description: "Registers a user in the global registry and triggers a welcome event.",
  tags: ["User Management"]
});

Automatic Schema Conversion

The Swagger plugin automatically converts your s schemas (Axeom Validators) into standard JSON Schema objects. This means your validation logic and your documentation are always perfectly in sync.

Configuration Options

Scalar UI Advantages

We chose Scalar as our default UI because it matches Axeom's performance philosophy:

• Fast: Incredibly lightweight and optimized for large API specs.

• Searchable: Built-in global search for endpoints and models.
• Integrated Client: Test your API directly from the browser with a beautiful request builder.