Feat: Example schemas (#309)

Author: jlalmes

README.md

@@ -66,9 +66,9 @@ export const openApiDocument = generateOpenApiDocument(appRouter, {
 
 **5. Add an `trpc-openapi` handler to your app.**
 
-We currently support adapters for [`Express`](http://expressjs.com/), [`Next.js`](https://nextjs.org/), [`Serverless`](https://www.serverless.com/) & [`Node:HTTP`](https://nodejs.org/api/http.html).
+We currently support adapters for [`Express`](http://expressjs.com/), [`Next.js`](https://nextjs.org/), [`Serverless`](https://www.serverless.com/), [`Fastify`](https://www.fastify.io/), [`Nuxt`](https://nuxtjs.org/) & [`Node:HTTP`](https://nodejs.org/api/http.html).
 
-[`Fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), [`Fastify`](https://www.fastify.io/), [`Nuxt`](https://nuxtjs.org/), [`Workers`](https://workers.cloudflare.com/) & more soon™, PRs are welcomed 🙌.
+[`Fetch`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), [`Cloudflare Workers`](https://workers.cloudflare.com/) & more soon™, PRs are welcomed 🙌.
 
 ```typescript
 import http from 'http';
@@ -179,7 +179,7 @@ Please see [error status codes here](src/adapters/node-http/errors.ts).
 
 ## Authorization
 
-To create protected endpoints, add `protect: true` to the `meta.openapi` object of each tRPC procedure. You can then authenticate each request with the `createContext` function using the `Authorization` header with the `Bearer` scheme.
+To create protected endpoints, add `protect: true` to the `meta.openapi` object of each tRPC procedure. By default, you can then authenticate each request with the `createContext` function using the `Authorization` header with the `Bearer` scheme. If you wish to authenticate requests using a different/additional methods (such as custom headers, or cookies) this can be overwritten by specifying `securitySchemes` object.
 
 Explore a [complete example here](examples/with-nextjs/src/server/router.ts).
 

src/generator/paths.ts

@@ -66,20 +66,35 @@ export const getOpenApiPathsObject = (
           security: protect ? securitySchemeNames.map((name) => ({ [name]: [] })) : undefined,
           ...(acceptsRequestBody(method)
             ? {
-                requestBody: getRequestBodyObject(inputParser, pathParameters, contentTypes),
+                requestBody: getRequestBodyObject(
+                  inputParser,
+                  pathParameters,
+                  contentTypes,
+                  openapi.example?.request,
+                ),
                 parameters: [
                   ...headerParameters,
-                  ...(getParameterObjects(inputParser, pathParameters, 'path') || []),
+                  ...(getParameterObjects(
+                    inputParser,
+                    pathParameters,
+                    'path',
+                    openapi.example?.request,
+                  ) || []),
                 ],
               }
             : {
                 requestBody: undefined,
                 parameters: [
                   ...headerParameters,
-                  ...(getParameterObjects(inputParser, pathParameters, 'all') || []),
+                  ...(getParameterObjects(
+                    inputParser,
+                    pathParameters,
+                    'all',
+                    openapi.example?.request,
+                  ) || []),
                 ],
               }),
-          responses: getResponsesObject(outputParser),
+          responses: getResponsesObject(outputParser, openapi.example?.response),
           ...(openapi.deprecated ? { deprecated: openapi.deprecated } : {}),
         },
       };

src/generator/schema.ts

@@ -24,6 +24,7 @@ export const getParameterObjects = (
   schema: unknown,
   pathParameters: string[],
   inType: 'all' | 'path' | 'query',
+  example: Record<string, any> | undefined,
 ): OpenAPIV3.ParameterObject[] | undefined => {
   if (!instanceofZodType(schema)) {
     throw new TRPCError({
@@ -107,6 +108,7 @@ export const getParameterObjects = (
         required: isPathParameter || (isRequired && isShapeRequired),
         schema: openApiSchemaObject,
         description: description,
+        example: example?.[shapeKey],
       };
     });
 };
@@ -115,6 +117,7 @@ export const getRequestBodyObject = (
   schema: unknown,
   pathParameters: string[],
   contentTypes: OpenApiContentType[],
+  example: Record<string, any> | undefined,
 ): OpenAPIV3.RequestBodyObject | undefined => {
   if (!instanceofZodType(schema)) {
     throw new TRPCError({
@@ -139,8 +142,12 @@ export const getRequestBodyObject = (
 
   // remove path parameters
   const mask: Record<string, true> = {};
+  const dedupedExample = example && { ...example };
   pathParameters.forEach((pathParameter) => {
     mask[pathParameter] = true;
+    if (dedupedExample) {
+      delete dedupedExample[pathParameter];
+    }
   });
   const dedupedSchema = unwrappedSchema.omit(mask);
 
@@ -149,6 +156,7 @@ export const getRequestBodyObject = (
   for (const contentType of contentTypes) {
     content[contentType] = {
       schema: openApiSchemaObject,
+      example: dedupedExample,
     };
   }
 
@@ -158,7 +166,7 @@ export const getRequestBodyObject = (
   };
 };
 
-export const errorResponseObject = {
+export const errorResponseObject: OpenAPIV3.ResponseObject = {
   description: 'Error response',
   content: {
     'application/json': {
@@ -173,19 +181,23 @@ export const errorResponseObject = {
   },
 };
 
-export const getResponsesObject = (schema: unknown): OpenAPIV3.ResponsesObject => {
+export const getResponsesObject = (
+  schema: unknown,
+  example: Record<string, any> | undefined,
+): OpenAPIV3.ResponsesObject => {
   if (!instanceofZodType(schema)) {
     throw new TRPCError({
       message: 'Output parser expects a Zod validator',
       code: 'INTERNAL_SERVER_ERROR',
     });
   }
 
-  const successResponseObject = {
+  const successResponseObject: OpenAPIV3.ResponseObject = {
     description: 'Successful response',
     content: {
       'application/json': {
         schema: zodSchemaToOpenApiSchemaObject(schema),
+        example,
       },
     },
   };

src/types.ts

@@ -27,6 +27,10 @@ export type OpenApiMeta<TMeta = TRPCMeta> = TMeta & {
     headers?: (OpenAPIV3.ParameterBaseObject & { name: string; in?: 'header' })[];
     contentTypes?: OpenApiContentType[];
     deprecated?: boolean;
+    example?: {
+      request?: Record<string, any>;
+      response?: Record<string, any>;
+    };
   };
 };