mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
d6960c72bf
* Improve SEO metadata: fix titles, descriptions, and remove redundant OpenAPI descriptions - Remove description frontmatter from 19 API pages where the OpenAPI spec already supplies the description - Fix 2 titles that exceeded 60 characters (content-templates, content-types) - Improve 15 descriptions that were too short (<130 chars) or too long (>160 chars) to target 130-155 characters - All descriptions are unique and include relevant search terms Generated-By: mintlify-agent * re-add API descriptions * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm * Apply suggestion from @ethanpalm --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
102 lines
2.8 KiB
Plaintext
102 lines
2.8 KiB
Plaintext
---
|
|
title: "Fields"
|
|
description: "Use ParamField and ResponseField components to document API request and response parameters with types, defaults, and validation rules."
|
|
keywords: ["ParamField", "ResponseField", "request parameters", "response documentation"]
|
|
---
|
|
|
|
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](/api-playground/overview).
|
|
|
|
<ParamField path="param" type="string" required>
|
|
An example of a parameter field
|
|
</ParamField>
|
|
|
|
```mdx
|
|
<ParamField path="param" type="string" required>
|
|
An example of a parameter field
|
|
</ParamField>
|
|
```
|
|
|
|
### Properties
|
|
|
|
<ParamField body="query, path, body, or header" type="string">
|
|
Whether the parameter is a query, path, body, or header. Followed by the
|
|
parameter name.
|
|
</ParamField>
|
|
|
|
<ParamField body="type" type="string">
|
|
Expected type of the parameter's value.
|
|
|
|
Supports `number`, `string`, `boolean`, `object`.
|
|
|
|
Define arrays using the `[]` suffix. For example `string[]`.
|
|
|
|
</ParamField>
|
|
|
|
<ParamField body="required" type="boolean">
|
|
Indicate whether you require the parameter.
|
|
</ParamField>
|
|
|
|
<ParamField body="deprecated" type="boolean">
|
|
Indicate whether you have deprecated the parameter.
|
|
</ParamField>
|
|
|
|
<ParamField body="default" type="any">
|
|
Default value populated when the request value is empty
|
|
</ParamField>
|
|
|
|
<ParamField body="placeholder" type="string">
|
|
Placeholder text for the input in the playground.
|
|
</ParamField>
|
|
|
|
<ParamField body="children" type="string">
|
|
Description of the parameter (Markdown-enabled).
|
|
</ParamField>
|
|
|
|
## Response field
|
|
|
|
The `<ResponseField>` component defines the return values of an API.
|
|
|
|
<ResponseField name="response" type="string" required>
|
|
An example of a response field
|
|
</ResponseField>
|
|
|
|
```mdx
|
|
<ResponseField name="response" type="string" required>
|
|
A response field example
|
|
</ResponseField>
|
|
```
|
|
|
|
### Properties
|
|
|
|
<ResponseField name="name" type="string" required>
|
|
The name of the response value.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="type" type="string" required>
|
|
Expected type of the response value. This can be any arbitrary string.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="default" type="string">
|
|
The default value.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="required" type="boolean">
|
|
Indicate whether you require the response.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="deprecated" type="boolean">
|
|
Whether you have deprecated a field.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="pre" type="string[]">
|
|
Labels that appear before the name of the field.
|
|
</ResponseField>
|
|
|
|
<ResponseField name="post" type="string[]">
|
|
Labels that appear after the name of the field.
|
|
</ResponseField>
|