feat: support description field on openapi and swagger bodies (#725)

fastify · May 24, 2023 · 61229a8 · 61229a8
1 parent 4ea925c
commit 61229a8
Show file tree

Hide file tree

Showing 4 changed files with 85 additions and 0 deletions.
diff --git a/lib/spec/openapi/utils.js b/lib/spec/openapi/utils.js
@@ -257,6 +257,10 @@ function resolveBodyParams (body, schema, consumes, ref) {
   if (resolved && resolved.required && resolved.required.length) {
     body.required = true
   }
+
+  if (resolved && resolved.description) {
+    body.description = resolved.description
+  }
 }
 
 function resolveCommonParams (container, parameters, schema, ref, sharedSchemas, securityIgnores) {

diff --git a/lib/spec/swagger/utils.js b/lib/spec/swagger/utils.js
@@ -185,6 +185,7 @@ function resolveBodyParams (parameters, schema, ref) {
   parameters.push({
     name: 'body',
     in: 'body',
+    description: resolved && resolved.description ? resolved.description : undefined,
     schema: resolved
   })
 }

diff --git a/test/spec/openapi/schema.js b/test/spec/openapi/schema.js
@@ -811,6 +811,50 @@ test('support object properties with special names', async t => {
   })
 })
 
+test('support "description" keyword', async t => {
+  const opt = {
+    schema: {
+      body: {
+        type: 'object',
+        description: 'Body description',
+        properties: {
+          foo: {
+            type: 'number'
+          }
+        }
+      }
+    }
+  }
+
+  const fastify = Fastify()
+  await fastify.register(fastifySwagger, {
+    openapi: true
+  })
+  fastify.post('/', opt, () => { })
+  await fastify.ready()
+
+  const swaggerObject = fastify.swagger()
+  const api = await Swagger.validate(swaggerObject)
+
+  const definedPath = api.paths['/'].post
+  t.same(definedPath.requestBody, {
+    description: 'Body description',
+    content: {
+      'application/json': {
+        schema: {
+          description: 'Body description',
+          type: 'object',
+          properties: {
+            foo: {
+              type: 'number'
+            }
+          }
+        }
+      }
+    }
+  })
+})
+
 test('support query serialization params', async t => {
   const opt = {
     schema: {

diff --git a/test/spec/swagger/schema.js b/test/spec/swagger/schema.js
@@ -482,6 +482,42 @@ test('support "const" keyword', async t => {
   })
 })
 
+test('support "description" keyword', async t => {
+  const opt = {
+    schema: {
+      body: {
+        type: 'object',
+        description: 'Body description',
+        properties: {
+          foo: {
+            type: 'number'
+          }
+        }
+      }
+    }
+  }
+
+  const fastify = Fastify()
+  await fastify.register(fastifySwagger)
+  fastify.post('/', opt, () => { })
+  await fastify.ready()
+
+  const swaggerObject = fastify.swagger()
+  const api = await Swagger.validate(swaggerObject)
+
+  const definedPath = api.paths['/'].post
+  t.same(definedPath.parameters[0].description, 'Body description')
+  t.same(definedPath.parameters[0].schema, {
+    type: 'object',
+    description: 'Body description',
+    properties: {
+      foo: {
+        type: 'number'
+      }
+    }
+  })
+})
+
 test('no head routes by default', async (t) => {
   const fastify = Fastify({ exposeHeadRoutes: true })
   await fastify.register(fastifySwagger, {