Support A Way To Generate $ref's

[cmcnicholas]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

I would like to define my typebox schema and have it so fastify both understands this schema and this library can produce valid openapi json schema.

A key requirement to clean openapi json schema is the ability to define our models and reference them throughout the specification.

For example I have:

export const RefreshResponseApiModelSchema = Type.Object(
  {
    accessToken: Type.String(),
    refreshToken: Type.String(),
  },
  { $id: 'RefreshResponseApiModel' },
);

export type RefreshResponseApiModel = Static<typeof RefreshResponseApiModelSchema>;

and have tried to register these with fastify during initialisation:

export function addSchemas(app: FastifyInstance) {
  // other schema
  app.addSchema(RefreshResponseApiModelSchema);
}

They add correctly but the resulting documentation is not correct, I can see the schema is added as below and never referenced by the methods that use these schema:

      "def-3": {
        "type": "object",
        "properties": {
          "accessToken": {
            "type": "string"
          },
          "refreshToken": {
            "type": "string"
          }
        },
        "required": [
          "accessToken",
          "refreshToken"
        ],
        "title": "RefreshResponseApiModel"
      }

I've read through the docs and tickets but can't see this expressed anywhere.

Motivation

To have an openapi documentation with generated schema that can be used by other tools e.g. codegen to generate correct model types with proper naming.

Example

No response

[l2ysho]

I use similar setup as you and it is working for me, but I reference shared schemas with Type.Ref

example:

authResponse: Type.Ref('RefreshResponseApiModel') // you have to use exact name

[cmcnicholas]

I use similar setup as you and it is working for me, but I reference shared schemas with Type.Ref

example:

authResponse: Type.Ref('RefreshResponseApiModel') // you have to use exact name

do you find the type system works with this after using this? my understanding is Type.Ref() doesn't return the correct type for handlers to infer etc.

[l2ysho]

I use similar setup as you and it is working for me, but I reference shared schemas with Type.Ref
example:
authResponse: Type.Ref('RefreshResponseApiModel') // you have to use exact name

do you find the type system works with this after using this? my understanding is Type.Ref() doesn't return the correct type for handlers to infer etc.

Working as far as I know. I also generate fetch client from swagger to have e2e types and no complaints from FE guys.

[cmcnicholas]

I don't seem to have the right setup to achieve both type safety on handlers AND refs in openapi.json.

I've played with a few things now but nothing seems to stick.

Examples of models I define below:

import { Static, Type } from '@sinclair/typebox';
import { FastifySchema } from 'fastify';
import { FailResponseApiModelSchema } from './fail.model';

// POST /auth/login

export const LoginRequestBodyApiModelSchema = Type.Object(
  {
    email: Type.String(),
    password: Type.String(),
  },
  { $id: 'LoginRequestBodyApiModel' },
);

export type LoginRequestBodyApiModel = Static<typeof LoginRequestBodyApiModelSchema>;

export const LoginResponseApiModelSchema = Type.Object(
  {
    accessToken: Type.String(),
    refreshToken: Type.String(),
  },
  { $id: 'LoginResponseApiModel' },
);

export type LoginResponseApiModel = Static<typeof LoginResponseApiModelSchema>;

export const LoginApiModelSchema = {
  tags: ['auth'],
  body: LoginRequestBodyApiModelSchema,
  response: {
    200: LoginResponseApiModelSchema,
    401: FailResponseApiModelSchema,
    422: FailResponseApiModelSchema,
  },
} satisfies FastifySchema;

Then an example of the defined handler:

import { FastifyReplyTypeBox, FastifyRequestTypeBox } from 'fastify';
import { LoginApiModelSchema } from '../models/auth.model';

export const loginHandler = async function (
  request: FastifyRequestTypeBox<typeof LoginApiModelSchema>,
  reply: FastifyReplyTypeBox<typeof LoginApiModelSchema>,
) {
  // login stuff
}

Then gluing both together for my routes:

import { FastifyTypebox } from 'fastify';
import { loginHandler } from '../handlers/auth.handler';
import { LoginApiModelSchema } from '../models/auth.model';

export default async function (fastify: FastifyTypebox) {
  fastify.post('/auth/login', { schema: LoginApiModelSchema }, loginHandler);
}

This is before playing around with Type.Ref but it doesn't seem to matter if I:

1. Register with fastify.addSchema either the direct schema or a Type.Ref of the schema's name
2. I add $id ref names or not

If I change LoginApiModelSchema.body to be Type.Ref('...') then I don't get type safety on handlers.

Would be interested to see what your setup looks like, as you say if its just working then I'm doing something wrong here.

[gurgunday]

Which version of the plugin are you using?

[cmcnicholas]

Which version of the plugin are you using?

Fastify = 5.6.0
Type Provider = 5.2.0
TypeBox = 0.34.41

[cmcnicholas]

https://github.com/cmcnicholas/fastify-typebox-openapi-typed I've setup a bare bones version of the exact code I am using along with the generated openapi.json here if it helps others.

[l2ysho]

cmcnicholas/fastify-typebox-openapi-typed I've setup a bare bones version of the exact code I am using along with the generated openapi.json here if it helps others.

I reviewed all of my swagger related code and I found this line in swaggerOptions I have added 13 months ago

await fastifyInstance.register(fastifySwagger, {
	...swaggerOptions,
	refResolver: {
    	buildLocalReference: (json, baseUri, fragment, i) => json.$id?.toString() || `def-${i}`,
	},
});

so probably it was not working for me neither. I tried the same in your example with this result.

{
   "openapi":"3.0.0",
   "info":{
      "version":"9.5.1",
      "title":"@fastify/swagger"
   },
   "components":{
      "schemas":{
         "RequestModel":{
            "type":"object",
            "properties":{
               "a":{
                  "type":"number"
               },
               "b":{
                  "type":"string"
               },
               "c":{
                  "type":"boolean"
               }
            }
         },
         "ResponseModel":{
            "type":"object",
            "required":[
               "message"
            ],
            "properties":{
               "message":{
                  "type":"string"
               }
            }
         }
      }
   },
   "paths":{
      "/openapi.json":{
         "get":{
            "responses":{
               "200":{
                  "description":"Default Response"
               }
            }
         }
      },
      "/":{
         "get":{
            "responses":{
               "200":{
                  "description":"Default Response"
               }
            }
         }
      },
      "/test":{
         "get":{
            "parameters":[
               {
                  "schema":{
                     "type":"number"
                  },
                  "in":"query",
                  "name":"a",
                  "required":false
               },
               {
                  "schema":{
                     "type":"string"
                  },
                  "in":"query",
                  "name":"b",
                  "required":false
               },
               {
                  "schema":{
                     "type":"boolean"
                  },
                  "in":"query",
                  "name":"c",
                  "required":false
               }
            ],
            "responses":{
               "200":{
                  "description":"Default Response",
                  "content":{
                     "application/json":{
                        "schema":{
                           "type":"object",
                           "required":[
                              "message"
                           ],
                           "properties":{
                              "message":{
                                 "type":"string"
                              }
                           }
                        }
                     }
                  }
               }
            }
         }
      }
   }
}

[trim21]

for pre-v1 typebox:

export function Ref<T extends TSchema>(T: T, options?: UnsafeOptions): TRefUnsafe<T> {
  return Type.Unsafe<Static<T>>({ $ref: T.$id, ...options });
}

then

{
  body: Ref(Schema),
  ...
}

[trim21]

for v1 typebox

export function Ref<T extends TSchema>(t: T, options: TSchemaOptions = {}): TUnsafe<Static<T>> {
  const id = (t as unknown as Record<string, string | undefined>).$id;
  if (!id) {
    throw new Error('missing ID on schema');
  }
  return Unsafe<Static<T>>({ ...t, $ref: id, $id: undefined, ...options });
}

this works in body schema, (the whole body as ref or some property as ref).

And you need to add id to each schema being referred, and also add schema to fastify app before you register the handle that use that ref

[cmcnicholas]

Thanks all, using both suggestions above and moving to v1 typebox I've got it all working and its making sense 👍

[cmcnicholas]

Too soon, what appears is working from a build and typing perspective when I run actually against the API I now get FST_ERR_VALIDATION errors on request that look like "schema is false"

Example usage of the Ref method above using typebox v1.

const RoleApiModelSchema = Type.Union(
  [
    Type.Literal('system'),
    Type.Literal('admin'),
    Type.Literal('manager'),
    Type.Literal('scheduler'),
    Type.Literal('presiter'),
    Type.Literal('corer'),
    Type.Literal('qa'),
    Type.Literal('client'),
    Type.Literal('analyst'),
  ],
  { $id: 'RoleApiModel' },
);

const CreateUserRequestBodyApiModelSchema = Type.Object(
  {
    email: Type.String(),
    displayName: Type.String(),
    password: Type.String(),
    roles: Type.Array(Ref(RoleApiModelSchema)),
  },
  { $id: 'CreateUserRequestBodyApiModel' },
);

export const CreateUserApiModelSchema = {
  tags: ['users'],
  body: Ref(CreateUserRequestBodyApiModelSchema),
  response: {
    201: Ref(CreateUserResponseApiModelSchema),
    401: FailResponseApiModelRef,
    403: FailResponseApiModelRef,
    409: FailResponseApiModelRef,
    422: FailResponseApiModelRef,
  },
} satisfies FastifySchema;

I also am definitely registering these before any routes are loaded via fastify.addSchema(....)

If I simplify the model down to a bare minimum like below I still get "schema is false":

const CreateUserRequestBodyApiModelSchema = Type.Object(
  {
    email: Type.String(),
  },
  { $id: 'CreateUserRequestBodyApiModel' },
);

export const CreateUserApiModelSchema = {
  tags: ['users'],
  body: Ref(CreateUserRequestBodyApiModelSchema),
  response: {
    204: Type.Null(),
  },
} satisfies FastifySchema;

[cmcnicholas]

ok seem to narrow this down, the Validator Compiler seems unusable with this approach, disabling it makes it work: https://sinclairzx81.github.io/typebox/#/docs/compile/overview

e.g.

const fastify = Fastify({
    logger: true,
  })
    //.setValidatorCompiler(TypeBoxValidatorCompiler)
    .withTypeProvider<TypeBoxTypeProvider>();