title: For OpenAPI Specification 3 how should I define the parameter of a request body
body: <p>I want to define my API endpoints with swagger OAS 3.0.0. My API requires quite a few parameter in the request body and I would like to give a detailed explanation for each request body parameter. The older version of OAS allows for <code>"path" : { "endpoint" : { "in" : "body"}}}</code> which would be perfect because I can describe each parameter individually. However, for OAS 3.0.0 it is stated that parameter in request body should be defined using the <code>requestBody</code> field which does not support description(ie what is the parameter referring to) for each parameter. Is there anyway for me to describe each request body parameter in OAS 3.0.0.?</p>
  
  <p>This way of defining parameters is perfect for me as my clients will be able to see the various parameters clearly.</p>
  
  <pre><code>"parameters" : [{
        "name" : "phone_no",
        "in" : "body",
        "description" : "User mobile no. It should follow International format.",
        "required" : true,
        "explode" : true,
        "schema" : {
          "type" : "string",
          "example": "+XXXXXX"
        }
      }, {
        "name" : "signature",
        "in" : "body",
        "description" : "How to get signature ....",
        "required" : true,
        "explode" : true,
        "schema" : {
          "type" : "string",
          "example" : "XXXXXXXXXXX"
        }
      } ]
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/IJ4yI.png" rel="nofollow noreferrer">Good readable request body parameters</a></p>
  
  <p>According to OAS 3.0.0 I should define the parameters in this format which is not ideal as the rendered API documentation will clump the definition of the parameters together which would be less readable for the client.</p>
  
  <pre><code>"requestBody" : {
        "description" : "HTTP Request Body",
        "content" : {
          "application/json" : {
            "schema" : {
              "properties" : {
                "phone_no" : {
                  "type" : "string",
                  "required" : true,
                  "description" : "User mobile no. It should follow International format."
                }, "signature" : {
                  "type" : "string",
                  "required" : true,
                  "description" : "How to get signature ...."
                }
              }
            }
          }
        }
      }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/d1FFN.png" rel="nofollow noreferrer">Less readable Request Body parameters</a></p>