Class RPCApiSpecGenerator

packages/server/src/api/rpc/openapi.ts:128–765

 * Generates an OpenAPI v3.1 specification for the RPC-style API handler.
 */
export class RPCApiSpecGenerator<Schema extends SchemaDef = SchemaDef> {
    private specOptions?: OpenApiSpecOptions;
    private readonly factory: ZodSchemaFactory<Schema>;
    /**
     * Schemas extracted from the Zod registry, keyed by their registered ID, with
     * all `$ref` values already rewritten to `#/components/schemas/<id>`.
     */
    private registrySchemas: Record<string, SchemaObject> = {};

    constructor(private readonly handlerOptions: RPCApiHandlerOptions<Schema>) {
        this.factory = createQuerySchemaFactory(handlerOptions.schema, handlerOptions.queryOptions);
    }

    private get schema(): SchemaDef {
        return this.handlerOptions.schema;
    }

    private get queryOptions() {
        return this.handlerOptions?.queryOptions;
    }

    generateSpec(options?: OpenApiSpecOptions): OpenAPIV3_1.Document {
        this.specOptions = options;

        // Build all model/procedure schemas eagerly and capture the full registry as
        // JSON Schema, then transform bare-ID $refs to OpenAPI component paths.
        const rawRegistry = this.factory.toJSONSchema();
        this.registrySchemas = this.transformRegistrySchemas(rawRegistry.schemas);

        return {
            openapi: '3.1.0',
            info: {
                title: options?.title ?? DEFAULT_SPEC_TITLE,
                version: options?.version ?? DEFAULT_SPEC_VERSION,
                ...(options?.description && { description: options.description }),
                ...(options?.summary && { summary: options.summary }),
            },
            tags: this.generateTags(),
            paths: this.generatePaths(),
            components: {
                schemas: {
                    ...this.registrySchemas,
                    ...this.generateSharedSchemas(),
                },
            },
        } as OpenAPIV3_1.Document;
    }

    /**
     * Takes the raw `schemas` map from `z.toJSONSchema(registry)` and:
     *  1. Rewrites bare-ID `$ref` values (e.g. `"UserWhereInput"`) to full
     *     component paths (`"#/components/schemas/UserWhereInput"`).
     *  2. Strips the `$schema` keyword from each top-level schema object, as it
     *     is redundant inside an OpenAPI document.
     *  3. Resolves Zod's auto-generated `__shared/$defs/schemaN` aliases.
     *     When a `__shared/$defs/schemaN` entry is itself a plain `$ref` to a
     *     named schema, every reference to it is rewritten to point directly at
     *     the target schema, removing the double indirection. Any remaining