feat: support local reference in schema, support definitions keyword

lib/spec/openapi/utils.js

@@ -98,8 +98,18 @@ function transformDefsToComponents (jsonSchema) {
         Object.keys(jsonSchema[key]).forEach(function (prop) {
           jsonSchema[key][prop] = transformDefsToComponents(jsonSchema[key][prop])
         })
+        // definitions are not allowed in openapi schema, so we mutate them to properties
+      } else if (key === 'definitions') {
+        jsonSchema.properties = {
+          ...transformDefsToComponents(jsonSchema[key]),
+          ...jsonSchema.properties
+        }
+        delete jsonSchema[key]
       } else if (key === '$ref') {
+        // replace the top-lvl path
         jsonSchema[key] = jsonSchema[key].replace('definitions', 'components/schemas')
+        // replace the path for nested defs
+        jsonSchema[key] = jsonSchema[key].replaceAll('definitions', 'properties')
       } else if (key === 'examples' && Array.isArray(jsonSchema[key]) && (jsonSchema[key].length > 1)) {
         jsonSchema.examples = convertExamplesArrayToObject(jsonSchema.examples)
       } else if (key === 'examples' && Array.isArray(jsonSchema[key]) && (jsonSchema[key].length === 1)) {
@@ -402,16 +412,16 @@ function prepareOpenapiSchemas (schemas, ref) {
   return Object.entries(schemas)
     .reduce((res, [name, schema]) => {
       const _ = { ...schema }
-      const resolved = transformDefsToComponents(ref.resolve(_, { externalSchemas: [schemas] }))
 
-      // Swagger doesn't accept $id on /definitions schemas.
-      // The $ids are needed by Ref() to check the URI so we need
-      // to remove them at the end of the process
-      // definitions are added by resolve but they are replace by components.schemas
-      delete resolved.$id
-      delete resolved.definitions
+      const resolvedRef = ref.resolve(_, { externalSchemas: [schemas] })
+
+      // swagger doesn't accept $id on components schemas
+      // $ids are needed only for ref.resolve to check the URI
+      delete resolvedRef.$id
+
+      const components = transformDefsToComponents(resolvedRef)
 
-      res[name] = resolved
+      res[name] = components
       return res
     }, {})
 }

test/spec/openapi/refs.js

@@ -282,3 +282,39 @@ test('uses examples if has property required in body', async (t) => {
   t.ok(schema.parameters)
   t.same(schema.parameters[0].in, 'query')
 })
+
+test('support absolute $ref inside the json-schema definitions', async (t) => {
+  const fastify = Fastify()
+
+  await fastify.register(fastifySwagger, openapiOption)
+  fastify.register(async (instance) => {
+    instance.addSchema({
+      $id: 'NestedSchema',
+      definitions: {
+        SchemaA: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' }
+          }
+        },
+        SchemaB: {
+          type: 'object',
+          properties: {
+            example: { $ref: 'NestedSchema#/definitions/SchemaA' }
+          }
+        }
+      }
+    })
+    instance.post('/url1/:test', { schema: { body: { $ref: 'NestedSchema#/definitions/SchemaB' }, params: { $ref: 'NestedSchema#/definitions/SchemaA' }, response: { 200: { $ref: 'NestedSchema#/definitions/SchemaA' } } } }, () => {})
+  })
+
+  await fastify.ready()
+
+  const openapiObject = fastify.swagger()
+  t.equal(typeof openapiObject, 'object')
+
+  //  ref must be prefixed by '#/components/schemas/'
+  t.equal(openapiObject.components.schemas.NestedSchema.properties.SchemaB.properties.example.$ref, '#/components/schemas/NestedSchema/properties/SchemaA')
+
+  await Swagger.validate(openapiObject)
+})

test/spec/openapi/schema.js

@@ -10,6 +10,15 @@ const {
   schemaAllOf
 } = require('../../../examples/options')
 
+const openapiOptionWithResolver = {
+  openapi: {},
+  refResolver: {
+    buildLocalReference: (json, baseUri, fragment, i) => {
+      return json.$id || `def-${i}`
+    }
+  }
+}
+
 test('support - oneOf, anyOf, allOf', async (t) => {
   t.plan(2)
   const fastify = Fastify()
@@ -785,3 +794,100 @@ test('support query serialization params', async t => {
   t.equal(api.paths['/'].get.parameters[0].style, 'deepObject')
   t.equal(api.paths['/'].get.parameters[0].explode, false)
 })
+
+test('support json-schema definitions keyword in schema(merge)', async t => {
+  const fastify = Fastify()
+  await fastify.register(fastifySwagger, openapiOptionWithResolver)
+
+  const schema = {
+    $id: 'NestedSchema',
+    properties: {
+      id: { type: 'string' }
+    },
+    definitions: {
+      SchemaA: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' }
+        }
+      },
+      SchemaB: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' }
+        }
+      }
+    }
+  }
+
+  fastify.register(async (instance) => {
+    instance.addSchema(schema)
+  })
+
+  await fastify.ready()
+
+  const openapiObject = fastify.swagger()
+  t.equal(typeof openapiObject, 'object')
+
+  // definitions are getting merged to properties
+  t.match(Object.keys(openapiObject.components.schemas), ['NestedSchema'])
+  t.match(Object.keys(openapiObject.components.schemas.NestedSchema), ['properties'])
+  t.match(Object.keys(openapiObject.components.schemas.NestedSchema.properties), ['SchemaA', 'SchemaB', 'id'])
+
+  await Swagger.validate(openapiObject)
+})
+
+test('prefer properties when merging json-schema definitions with properties', async t => {
+  const fastify = Fastify()
+  await fastify.register(fastifySwagger, openapiOptionWithResolver)
+
+  const schema = {
+    $id: 'NestedSchema',
+    properties: {
+      SchemaA: {
+        $id: 'SchemaA',
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          name: { type: 'string' },
+          description: { type: 'string' }
+        }
+      }
+    },
+    definitions: {
+      SchemaA: {
+        $id: 'SchemaA',
+        type: 'object',
+        properties: {
+          id: { type: 'string' }
+        }
+      },
+      SchemaB: {
+        $id: 'SchemaB',
+        type: 'object',
+        properties: {
+          id: { type: 'string' }
+        }
+      }
+    }
+  }
+
+  fastify.register(async (instance) => {
+    instance.addSchema(schema)
+  })
+
+  await fastify.ready()
+
+  const openapiObject = fastify.swagger()
+  t.equal(typeof openapiObject, 'object')
+
+  t.same(openapiObject.components.schemas.NestedSchema.properties.SchemaA, {
+    type: 'object',
+    properties: {
+      id: { type: 'string' },
+      name: { type: 'string' },
+      description: { type: 'string' }
+    }
+  })
+  await Swagger.validate(openapiObject)
+})