Defining the request body for an operation

A request body defines the structure of the body of an API request.

About this task

Note:
  • This task relates to configuring an OpenAPI 3.0 API definition. For details on how to configure an OpenAPI 2.0 API definition, see Editing an OpenAPI 2.0 API definition.
  • OpenAPI 3.0 APIs are supported only with the DataPower® API Gateway, not with the DataPower Gateway (v5 compatible).
  • For details of current OpenAPI 3.0 support limitations, see OpenAPI 3.0 support in IBM® API Connect.

You can complete this task either by using the API Designer UI application, or by using the browser based API Manager UI.

At any time, you can switch directly to the underlying OpenAPI YAML source that corresponds to the design form in the user interface by clicking the Source icon OpenAPI Source icon. To return to the design form, click the Form icon Form icon.

Note: The user interface doesn't currently support referencing a request body component from an operation. However, you can add the reference directly to the OpenAPI YAML source for your API definition, for example:
paths:
  /mypath:
    get:
          .
          .
          .
      requestBody:
        $ref: '#/components/requestBodies/my_requestbody_component'
          .
          .
          .

For information on request body components, see Defining request body components.

Procedure

  1. Open the required API for editing, as described in Editing an OpenAPI 3.0 API definition.
  2. Expand Paths, then expand the required Path.
  3. Expand Operations, expand the required operation, then click requestBody.
  4. Provide the following information:
    • Description: An optional description of the request body. This could contain examples of use. You can use CommonMark syntax for rich text representation.
    • Content: A content definition describes the content of the request body.

      To define a new content definition for the request body, click Add, then refer to Creating a content definition.

      To edit an existing content definition, click the content definition name, then refer to Editing a content definition.

    • Required: Determines if the request body is required in the request.
  5. Click Save when done.