feat: support description field on openapi and swagger bodies

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) {

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
   })
 }

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: {

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, {