feat: Add Model Schemas to OpenApi Docs

[calasanmarko]

From issue #157 :

I needed a way to integrate my OpenAPI-extended Zod schemas (using @asteasolutions/zod-to-openapi) with the rest of the document generated by trpc-openapi, so I threw this together in an afternoon.

This implementation integrates a registry of Zod schemas into the final document, and also links return, parameter, and request body types of tRPC procedures with these schemas.

A minimal example of how this looks with @asteasolutions/zod-to-openapi (although it should work with any solution):

import { OpenAPIRegistry, OpenApiGeneratorV3 } from "@asteasolutions/zod-to-openapi";
import { setZodComponentDefinitions, setZodComponentSchemaGenerator } from "trpc-openapi";
import { z } from "zod";

const registry = new OpenAPIRegistry();
registry.register("ComponentName", z.object({
    // ...
}))

const generator = new OpenApiGeneratorV3(registry.definitions);

// ~~~ FUNCTIONS FROM THE PR BELOW ~~~

// The definitions are used to map the types referenced in tRPC procedures
setZodComponentDefinitions(registry.definitions.reduce((acc, d) => {
    if (d.type === 'schema') {
        acc[d.schema._def.openapi._internal.refId] = d.schema;
    }
    return acc;
}, {} as { [key: string]: z.ZodType }));

// The schema generator generates the actual components in the OpenAPI document
setZodComponentSchemaGenerator(() => generator.generateDocument(config).components?.schemas ?? {});

[tonyxiao]

Can this work with other generators notably https://github.com/samchungy/zod-openapi?

[calasanmarko]

I don't see why not -- it should work as long as the generator embeds a reference ID somewhere in the object definition, which a cursory glance at zod-openapi tells me it does just that -- see https://github.com/samchungy/zod-openapi#auto-registering-schema

I might take it upon myself to test it in the next few days, but it would almost certainly work.

[tonyxiao]

That'd be awesome. samchungy's version is an evolution of the @asteasolutions/zod-to-openapi one

[tonyxiao]

Just found this fork and it seems to work like a charm!

[tonyxiao]

https://github.com/lilyrose2798/trpc-openapi

Wonder if the two PRs overlap / can be used together or are there conflicting ideas?

[tonyxiao]

@calasanmarko can you look take a look at the fork from @LilyRose2798 too? Seems to contain the same functionalities but more robust and supports optional schema registration.

[devidw]

Also needed support for this and did my own implementation: https://github.com/devidw/trpc-openapi

It's a quick implementation, but if you would be interested in merging it into upstream I am happy to clean it up a bit and submit a PR. @jlalmes