Fallback to reference description for responses

Author: Nelspike

lib/spec/openapi/utils.js

@@ -303,6 +303,17 @@ function resolveCommonParams (container, parameters, schema, ref, sharedSchemas,
   arr.forEach(swaggerSchema => parameters.push(swaggerSchema))
 }
 
+// Keys to references could be different than the name of the $ref,
+// for example `def-0`
+function findReference (definitions, id) {
+  const schemaKey = Object.keys(definitions).find(key => {
+    const schema = definitions[key]
+    return schema.$id === id
+  })
+
+  return definitions[schemaKey] ?? {}
+}
+
 // https://swagger.io/docs/specification/describing-responses/
 function resolveResponse (fastifyResponseJson, produces, ref) {
   // if the user does not provided an out schema
@@ -313,6 +324,7 @@ function resolveResponse (fastifyResponseJson, produces, ref) {
   const responsesContainer = {}
 
   const statusCodes = Object.keys(fastifyResponseJson)
+  const definitions = ref.definitions().definitions
 
   statusCodes.forEach(statusCode => {
     const rawJsonSchema = fastifyResponseJson[statusCode]
@@ -326,8 +338,13 @@ function resolveResponse (fastifyResponseJson, produces, ref) {
       statusCode = statusCode.toUpperCase()
     }
 
+    const referenceJsonSchema = findReference(definitions, rawJsonSchema.$ref)
+
     const response = {
-      description: resolved[xResponseDescription] || rawJsonSchema.description || 'Default Response'
+      description: referenceJsonSchema.description ||
+        resolved[xResponseDescription] ||
+        rawJsonSchema.description ||
+        'Default Response'
     }
 
     // add headers when there are any.

test/spec/openapi/schema.js

@@ -387,6 +387,41 @@ test('response: description and x-response-description', async () => {
     t.equal(schemaObject.description, description)
     t.equal(schemaObject.responseDescription, undefined)
   })
+
+  test('retrieve the response description from its given $ref schema', async t => {
+    // Given a /description endpoint that also has a |description| field in its response referenced schema
+    const fastify = Fastify()
+    await fastify.addSchema({
+      $id: 'my-ref',
+      description,
+      type: 'string'
+    })
+
+    await fastify.register(fastifySwagger, openapiOption)
+    fastify.get('/description', {
+      schema: {
+        response: {
+          200: {
+            $ref: 'my-ref'
+          }
+        }
+      }
+    }, () => {})
+    await fastify.ready()
+
+    // When the Swagger schema is generated
+    const swaggerObject = fastify.swagger()
+    const api = await Swagger.validate(swaggerObject)
+
+    const responseObject = api.paths['/description'].get.responses['200']
+    t.ok(responseObject)
+    t.equal(responseObject.description, description)
+
+    const schemaObject = responseObject.content['application/json'].schema
+    t.ok(schemaObject)
+    t.equal(schemaObject.description, description)
+    t.equal(schemaObject.responseDescription, undefined)
+  })
 })
 
 test('support default=null', async t => {