Extract description from the request body and use it as description in the OpenAPI Request Body Object

[steckhelena]

Prerequisites

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

🚀 Feature Proposal

Currently, the generated OpenAPI spec generated for the following body:

fastify.post(
  '/',
  {
    schema: {
      body: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
          },
        },
        required: ['name'],
        description: 'A greeting object',
      },
    },
  },
  async (request) => {
    return `Hello, ${request.body.name}`
  },
)

will be something as follows (removing other information that is not paths):

{
  "paths": {
    "/": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": ["name"],
                "description": "A greeting object" // the description is inside the schema
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    }
  }
}

While the OpenAPI spec uses the following format:

{
  "paths": {
    "/": {
      "post": {
        "requestBody": {
          "description": "A greeting object" // notice the body description here
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  }
                },
                "required": ["name"],
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Default Response"
          }
        }
      }
    }
  }
}

That is: the description key is at the same level as the content key.

So I propose to add the option or make it the default, to add the description to the same level as the content key.

Motivation

Adequate the output for use with UI documentation generators (in my case, Redoc)

Example

It could either be something like:

fastify.post(
  '/',
  {
    schema: {
      body: {
        type: 'object',
        properties: {
          name: {
            type: 'string',
          },
        },
        required: ['name'],
        x-request-body-description: 'A greeting object',
      },
    },
  },
  async (request) => {
    return `Hello, ${request.body.name}`
  },
)

or keep the same description property and output the description in both places, inside the MediaType and the Request Body Object (I prefer this, but I don't know how it would interact with the rest of the library).

[mcollina]

Thanks for reporting! Would you like to send a Pull Request to address this issue? Remember to add unit tests.

[steckhelena]

I can write a pull request, as I fixed it locally with a patch. However, I can only get to it next week. Is outputting the description property on both places okay in this case? (inside the MediaType and the Request Body Object?)

[mcollina]

Let's do that and see the results.