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()`

Gather all procedures and compile the OpenAPI JSON specification:


import { generateOpenApi } from "@explita/actyx-rpc";
import { getProfile, updateUser, deletePost } from "./procedures";
 
const openapi = generateOpenApi(
  {
    // Simple registration
    "get-profile": getProfile,
 
    // 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",
    baseUrl: "https://api.example.com/v1",
    security: true,            // Enables default Bearer Auth (JWT)
    output: "./openapi.json",  // Output path (writes JSON file)
  }
);

Generation Features

Recursive Schema Mapping: Automatically parses schema trees generated by Zod, ArkType, Valibot, Yup, and Joi.
Smart Examples: Inspects validation objects to pre-populate request bodies and output formats in documentation tools.
Auto Parameter Mapping: Places Query parameters into search/query parameters, and Mutation payloads into request bodies.
JWT Configuration: Toggle security: true to inject standard Authorization Bearer schemes across all paths.