alepha@docs:~/docs/guides/server$
cat 2-openapi.md
2 min read
Last commit:

#OpenAPI Documentation

Alepha auto-generates OpenAPI 3.0 specifications from your $action definitions using the $swagger primitive.

#Setup

typescript 
 1import { $swagger } from "alepha/server/swagger"; 2  3class App { 4  docs = $swagger({ 5    info: { 6      title: "My API", 7      version: "1.0.0", 8      description: "Product catalog REST API", 9    },10  });11}

This serves:

  • Interactive Swagger UI at /docs
  • OpenAPI JSON at /docs/json

#Configuration

The $swagger primitive accepts these options:

Option Default Description
info { title: "API Documentation", version: "1.0.0" } OpenAPI info block
prefix "/docs" Base path for documentation endpoints
disabled false Disable documentation entirely
excludeTags [] Tag names to hide from documentation
ui true Enable/disable Swagger UI, or pass UI options
rewrite - Function to modify the generated OpenAPI document

#Custom Prefix

typescript 
1docs = $swagger({2  prefix: "/api-docs",3  info: { title: "My API", version: "2.0.0" },4});5// Swagger UI at /api-docs, JSON at /api-docs/json

#Excluding Tags

Tags correspond to action groups (class names by default). Hide internal endpoints:

typescript 
1docs = $swagger({2  info: { title: "Public API", version: "1.0.0" },3  excludeTags: ["InternalController", "admin"],4});

#Rewriting the Document

Modify the generated OpenAPI document before it is served:

typescript 
 1docs = $swagger({ 2  info: { title: "My API", version: "1.0.0" }, 3  rewrite: (doc) => { 4    doc.components ??= {}; 5    doc.components.securitySchemes = { 6      apiKey: { 7        type: "apiKey", 8        in: "header", 9        name: "X-API-Key",10      },11    };12  },13});

#How Actions Map to OpenAPI

Each $action with a schema becomes an OpenAPI operation:

  • Operation ID -- The action name (property key or explicit name).
  • Tag -- The action group (class name or explicit group).
  • Summary/Description -- From the summary and description options on $action.
  • Parameters -- Generated from schema.params (path) and schema.query (query).
  • Request Body -- Generated from schema.body. Objects become application/json, file schemas become multipart/form-data.
  • Response -- Generated from schema.response.

Schema descriptions propagate to OpenAPI field descriptions:

typescript 
1schema: {2  body: t.object({3    email: t.email({ description: "User's email address" }),4    age: t.integer({ description: "User's age in years" }),5  }),6}

#Security in OpenAPI

When AlephaSecurity is registered, all actions are documented with Bearer JWT authentication by default. Actions with secure: false are excluded from the security requirement.

#OAuth Configuration

Pass OAuth initialization options for the Swagger UI:

typescript 
 1docs = $swagger({ 2  info: { title: "My API", version: "1.0.0" }, 3  ui: { 4    initOAuth: { 5      clientId: "my-client-id", 6      appName: "My App", 7      usePkceWithAuthorizationCodeGrant: true, 8    }, 9  },10});