Fields

Use ParamField and ResponseField components to document API request and response parameters with types, defaults, and validation rules.

Use fields to document API parameters and responses. There are two types of fields: parameter fields and response fields.

Parameter field

Use the <ParamField> component to define parameters for your APIs or SDKs. Adding a ParamField automatically adds an API Playground.

paramstringrequired

An example of a parameter field

<ParamField path="param" type="string" required>
  An example of a parameter field
</ParamField>

query, path, body, or headerstring

Whether the parameter is a query, path, body, or header. Followed by the parameter name.

typestring

Expected type of the parameter’s value.

Supports number, string, boolean, object.

Define arrays using the [] suffix. For example string[].

requiredboolean

Indicate whether you require the parameter.

deprecatedboolean

Indicate whether you have deprecated the parameter.

defaultany

Default value populated when the request value is empty

placeholderstring

Placeholder text for the input in the playground.

childrenstring

Description of the parameter (Markdown-enabled).

The <ResponseField> component defines the return values of an API.

responsestringrequired

An example of a response field

<ResponseField name="response" type="string" required>
  A response field example
</ResponseField>

namestringrequired

The name of the response value.

typestringrequired

Expected type of the response value. This can be any arbitrary string.

defaultstring

The default value.

requiredboolean

Indicate whether you require the response.

deprecatedboolean

Whether you have deprecated a field.

prestring[]

Labels that appear before the name of the field.

poststring[]

Labels that appear after the name of the field.