Setup

Arkos automatically generates OpenAPI documentation for your API — no manual schemas, no JSDoc blocks, no mode selection. Validation schemas drive the docs, and Prisma models fill in the gaps.

Once configured, visit /api/docs to view your interactive documentation.

Configuration

import { defineConfig } from "arkos/config";

export default defineConfig({
  swagger: {
    endpoint: "/api/docs",
    options: {
      definition: {
        openapi: "3.1.0",
        info: {
          title: "My API",
          version: "1.0.0",
        },
        servers: [
          {
            url: "http://localhost:8000",
            description: "Development",
          },
        ],
      },
    },
  },
});

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  swagger: {
    endpoint: "/api/docs",
    options: {
      definition: {
        openapi: "3.1.0",
        info: {
          title: "My API",
          version: "1.0.0",
        },
      },
    },
  },
};

export default arkosConfig;

import arkos from "arkos";

arkos.init({
  swagger: {
    endpoint: "/api/docs",
    options: {
      definition: {
        openapi: "3.1.0",
        info: {
          title: "My API",
          version: "1.0.0",
        },
      },
    },
  },
});

Scalar UI

Arkos uses Scalar as the API documentation UI. Customize its appearance:

export default defineConfig({
  swagger: {
    // ... other config
    scalarApiReferenceConfiguration: {
      theme: "deepSpace",     // or "default", "alternate", "saturn"
      darkMode: true,
      layout: "modern",
      customCss: `
        .scalar-app {
          font-family: 'Inter', sans-serif;
        }
      `,
    },
  },
});

Available themes: default, alternate, deepSpace, saturn, kepler

How It Works

Arkos builds your OpenAPI spec from two sources:

1. Validation schemas — When you add validation to a route (custom or built-in), Arkos converts your Zod schemas or class-validator DTOs to OpenAPI schemas
2. Prisma models — For built-in routes without validation, Arkos generates schemas directly from your Prisma models and query options

No mode. No manual work. Just configure and go.

Next Steps

• Documenting Routes — Add summaries, descriptions, and custom responses
• Prisma Integration — How query options shape generated schemas
• File Uploads Integration — Automatic multipart/form-data documentation
• Authentication Integration — Document auth endpoints and security schemes
• Migration Guide — Upgrade from JSDoc to ArkosRouter