Forum Discussion

klementtan's avatar
klementtan
New Member
6 years ago

Describing requestBody parameters

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 "path" : { "endpoint" : { "in" : "body"}}} 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 requestBody 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.?
  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)
    6 years ago

    OpenAPI 3.0 supports the description field in the requestBody itself, the requestBody schema, and individual schema fields.

    openapi: 3.0.2
...
paths:
  /login:
    post:
      requestBody:
        required: true
        description: A JSON object containing the username and password  # <----
        content:
          application/json:
            schema:
              type: object
              description: An object containing the username and password  # <----
              properties:
                username:
                  type: string
                  description: Your username  # <----
                password:
                  type: string
                  description: Your password  # <----
              required:
                - username
                - password
      responses:
        200:
          description: Successful login

    Please see Describing Request Body for more examples.