RFC: Add Model Schemas to OpenApi Docs

[chuckstock]

First, I'm loving the project so far and I really appreciate all the work you've done already.

I honestly don't mind the output requirement on a query/mutation, however, it would be nice to be able to define Model Schema's and reference those for the outputs inside the docs. (ex. Pet Model from Redoc).

[jlalmes]

Hi @chuckstock. I have added this feature as a "Maybe" in our v1.0.0 roadmap (#91). Any ideas how you would like this API to look/behave?

Initial thoughts 👇

// models.ts
export const User = z.object({
  id: z.string().uuid(),
  name: z.string(),
});

// router.ts
import { User } from './models';
export const appRouter = trpc.router().query('getUsers', {
  meta: { openapi: { ... } },
  input: ...,
  output: z.array(User),
  resolve: ...
});

// openapi.json.ts
import { User } from './models';
import { appRouter } from './router';

const openapi = generateOpenApiDocument(appRouter, {
  ...,
  models: [User]
});

cc @StefanTerdell.

[chuckstock]

Yeah this is almost exactly what I was thinking and was potentially expecting to find when reviewing the documentation. I think that makes a lot of sense without adding really any extra boilerplate or overhead.

Another package allows you to extend ZodObjects and turn them into openapi components, here is an example from their npm packaage:

import { extendApi, generateSchema } from '@anatine/zod-openapi';
const aZodExtendedSchema = extendApi(
      z.object({
        uid: extendApi(z.string().nonempty(), {
          title: 'Unique ID',
          description: 'A UUID generated by the server',
        }),
        firstName: z.string().min(2),
        lastName: z.string().optional(),
        email: z.string().email(),
        phoneNumber: extendApi(z.string().min(10), {
          description: 'US Phone numbers only',
          example: '555-555-5555',
        }),
      }),
      {
        title: 'User',
        description: 'A user schema',
      }
    );
const myOpenApiSchema = generateSchema(aZodExtendedSchema);

This is another suggestion, although I think I prefer your original suggestion for the API.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[OscBacon]

Hi, any updates on this?

[rehanvdm]

I am also very interested in this, its the only open issue on the previous roadmap. Can this still be looked at for a future release?