OpenAPI Spec Generation
Actyx RPC is self-documenting. By attaching metadata to procedures, you can generate complete OpenAPI 3.0 (Swagger) specifications automatically.
Documenting Procedures
Use .summary(), .description(), and .output() to document schemas and descriptions:
const createUser = procedure
.name("createUser")
.summary("Create a new system user")
.description("Registers a new user. Sends a welcome email. Requires admin privileges.")
.input(zodResolver(userSchema))
.output(zodResolver(userResponseSchema))
.mutation(async ({ input }) => { ... });.summary(text): A concise, single-line explanation of the procedure..description(text): A detailed, multi-line explanation of behavior, side effects, and rules..output(resolver): Explicit contract definition used to generate the output schema.
generateOpenApi()
Compile your router or procedures directly into a valid OpenAPI 3.1 specification:
import { generateOpenApi } from "@explita/actyx-rpc";
import { appRouter } from "./router";
const openapi = generateOpenApi(appRouter, {
title: "My System API",
version: "1.0.0",
baseUrl: "https://api.example.com",
security: true, // Enables Bearer Auth (JWT)
output: "./openapi.json", // Optional: writes spec to disk
});Passing Procedures with Custom Overrides
You can also pass a custom dictionary with overrides for specific HTTP methods or Swagger tags:
const openapi = generateOpenApi(
{
// Nested router or procedures
todos: appRouter.todos,
// Overriding defaults
"update-user": {
procedure: updateUser,
method: "put", // Force PUT method instead of default POST
tags: ["User Management"], // Set Swagger grouping tags
summary: "Admin update", // Override default procedure summary
},
"delete-post": {
procedure: deletePost,
method: "delete", // Map to standard DELETE request
tags: ["Posts"],
},
},
{
title: "My System API",
version: "1.0.0",
}
);Serving OpenAPI Over HTTP (createOpenApiHandler)
Instead of writing openapi.json to disk, you can serve the live specification directly over HTTP for Swagger UI, Scalar, Redoc, or Postman using createOpenApiHandler:
// app/api/openapi.json/route.ts
import { createOpenApiHandler } from "@explita/actyx-rpc/adapters/next";
import { appRouter } from "@/backend/router";
export const GET = createOpenApiHandler(appRouter, {
title: "Production API",
version: "1.0.0",
baseUrl: "https://api.example.com/api",
security: true,
});Generation Capabilities
- Nested Router Traversal: Automatically flattens arbitrary levels of
createRoutertrees into standardized paths (e.g./todos/list,/todos/add). - Native
@standard-schemaExtraction: Extracts JSON Schema property definitions directly from Zod, ArkType, Valibot, and Yup schemas without requiring third-party tools. - Server-Sent Events (
text/event-stream): Procedures defined with.stream()or.sse()automatically documenttext/event-streamresponse media types. - Smart Examples: Generates realistic sample inputs and responses from field validations.
- HTTP Method Alignment: GET/DELETE procedures map input schemas to URL query parameters; POST/PUT/PATCH procedures map to request bodies.
- JWT & API Key Schemes: Supports
security: truefor bearer auth, or custom security definitions.
Last updated on