Example OpenAPI Specification

Oct 13, 2025 by pinkandtrash.com 13 views

When the Body Parameter is of Reference Type in the Custom Tool, it Cannot be Requested to be Sent

In the context of API development, it is common to encounter scenarios where the body parameter is of reference type. However, when using a custom tool, it may not be possible to request the body parameter to be sent. This issue can be frustrating, especially when working with complex APIs. In this article, we will delve into the details of this problem and explore possible solutions.

A reference type body parameter is a type of parameter that references an existing schema or model. This type of parameter is commonly used in APIs that require complex data structures to be sent in the request body. In the OpenAPI specification, reference type body parameters are defined using the $ref keyword.

Example OpenAPI Specification

The following is an example of an OpenAPI specification that defines a reference type body parameter:

components:
  schemas:
    SalesDashboardDataVO:
      type: object
      properties:
        orderShopCount:
          type: integer
          description: orderShopCount
          format: int64
        ...

In this example, the SalesDashboardDataVO schema is defined as a reference type, which means that it can be used as a body parameter in an API request.

When using a custom tool to send API requests, it may not be possible to request the body parameter to be sent. This is because the custom tool may not support reference type body parameters or may not be able to parse the OpenAPI specification correctly.

Example Custom Tool Request

The following is an example of a custom tool request that attempts to send a reference type body parameter:

{
  "openapi": "3.0.1",
  "info": {
    "title": "xxx接口",
    "description": "",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://xxxx.com"
    }
  ],
  "paths": {
    "/teashop_supplier/supplier_oms_order/sales_dashboard_data": {
      "post": {
        "summary": "sales_dashboard_data",
        "deprecated": false,
        "description": "sales_dashboard_data",
        "tags": [],
        "parameters": [
          {
            "name": "Tenant-Id",
            "in": "header",
            "description": "Tenant-Id",
            "required": true
          },
          {
            "name": "Authorization",
            "in": "header",
            "description": "鉴权token",
            "required": true
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SalesDashboardDataQuery",
                "description": ""
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RSalesDashboardDataDTO"
                }
              }
            },
            "headers": {}
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "schemas": {
      "SalesDashboardDataVO": {
        "type": "object",
        "properties": {
          "orderShopCount": {
            "type": "integer",
            "description": "orderShopCount",
            "format": "int64"
          },
          ...

In this example, the custom tool request attempts to send a reference type body parameter, but it may not be possible to request the body parameter to be sent.

There are several possible solutions to this issue:

Use a different custom tool: If the custom tool you are using does not support reference type body parameters, you may need to use a different custom tool that does.
Modify the OpenAPI specification: If the custom tool you are using does not support reference type body parameters, you may need to modify the OpenAPI specification to remove the reference type body parameter.
Use a different API endpoint: If the custom tool you are using does not support reference type body parameters, you may need to use a different API endpoint that does not require a reference type body parameter.

In conclusion, when the body parameter is of reference type in the custom tool, it cannot be requested to be sent. This issue can be frustrating, especially when working with complex APIs. However, there are several possible solutions to this issue, including using a different custom tool, modifying the OpenAPI specification, and using a different API endpoint.

Based on our analysis, we recommend the following:

Use a different custom tool: If the custom tool you are using does not support reference type body parameters, we recommend using a different custom tool that does.
Modify the OpenAPI specification: If the custom tool you are using does not support reference type body parameters, we recommend modifying the OpenAPI specification to remove the reference type body parameter.
Use a different API endpoint: If the custom tool you are using does not support reference type body parameters, we recommend using a different API endpoint that does not require a reference type body parameter.

By following these recommendations, you should be able to resolve the issue of the body parameter being of reference type in the custom tool.
Q&A: When the Body Parameter is of Reference Type in the Custom Tool, it Cannot be Requested to be Sent

A: A reference type body parameter is a type of parameter that references an existing schema or model. This type of parameter is commonly used in APIs that require complex data structures to be sent in the request body.

A: There are several reasons why you may not be able to request the body parameter to be sent in your custom tool. Some possible reasons include:

The custom tool does not support reference type body parameters.
The custom tool is not able to parse the OpenAPI specification correctly.
The custom tool is not configured to send the body parameter.

A: There are several possible solutions to this issue. Some possible solutions include:

Using a different custom tool that supports reference type body parameters.
Modifying the OpenAPI specification to remove the reference type body parameter.
Using a different API endpoint that does not require a reference type body parameter.

A: Some common custom tools that support reference type body parameters include:

Postman
cURL
Swagger UI
API Gateway

A: To modify the OpenAPI specification to remove the reference type body parameter, you can follow these steps:

Open the OpenAPI specification file in a text editor.
Locate the reference type body parameter and remove it.
Save the changes to the OpenAPI specification file.

A: Some best practices for working with reference type body parameters include:

Using a consistent naming convention for reference type body parameters.
Documenting the reference type body parameter in the OpenAPI specification.
Testing the reference type body parameter thoroughly before deploying the API.

A: To troubleshoot issues with reference type body parameters, you can follow these steps:

Check the OpenAPI specification for errors or inconsistencies.
Verify that the custom tool is configured correctly to send the body parameter.
Test the API endpoint with a different custom tool or API client.

A: Some common errors that occur when working with reference type body parameters include:

"Reference type body parameter not supported"
"OpenAPI specification not parsed correctly"
"Custom tool not configured correctly to send body parameter"

In conclusion, working with reference type body parameters can be challenging, but with the right tools and best practices, you can resolve issues and troubleshoot problems. By following the recommendations and best practices outlined in this article, you can ensure that your API is working correctly and efficiently.