cancel
Showing results for 
Search instead for 
Did you mean: 

Describing requestBody parameters

New Member

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.?
1 REPLY 1
Moderator

Re: Describing requestBody parameters

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.


Helen Kosova
SmartBear Technical Writer
________________________
Vote up helpful replies.
Accept this reply if you think it's the best solution to your question.
New Here?
Join us and watch the welcome video:
6 / 7 API Testing Mistakes Video