Octri

ParamField and ResponseField

ParamField and ResponseField describe an API field on a page you write by hand: its name, type, where it goes, whether it's required and its default, with any explanation below. Every flag and setting in these docs is drawn with them.

Example

limitintegerquerydefault: 20

How many items to return, from 1 to 100.

customer_idstringpathrequired

The customer to fetch.

mdx
<ParamField name="limit" type="integer" in="query" default="20">
  How many items to return, from 1 to 100.
</ParamField>

<ParamField name="customer_id" type="string" in="path" required="true">
  The customer to fetch.
</ParamField>

ParamField props

namestring

The field's name, shown in code style.

typestring

Its type, shown beside the name, such as string, integer or object[].

instring

Where it's sent, such as query, path, header or body. Shown as a hint.

requiredboolean

Marks the field as required. Write required or required="true". required="false" leaves it optional.

defaultstring

The value used when the caller leaves the field out.

childrenMarkdown

The explanation, between the tags. It can hold tables, lists and code.

ResponseField

The same props, for a field in a response. A response field is either present or not, so required matters less here.

next_cursorstring

Pass this as cursor to get the next page. Absent on the last page.

mdx
<ResponseField name="next_cursor" type="string">
  Pass this as `cursor` to get the next page. Absent on the last page.
</ResponseField>
Let your spec do this where it can

Endpoint pages build their parameters and responses from your spec, and stay correct when it changes. A field written by hand doesn't. Link to the endpoint page instead of repeating it, unless you're explaining something the spec can't say.