API docs components
Build out your API docs pages with flexible page elements.
When creating API documentation with Basedoc, you can build pages with different page components that are on offer.
This means you have flexibility with how your API docs pages are displayed to users, or you can go super minimalist and let Basedoc do the heavy lifting.
API Components
The API endpoint that you defined in the page's frontmatter can be rendered in the page using the following components.
| Component | Usage | Description |
|---|---|---|
<Endpoint /> | Always | Renders method, path and summary |
<Params /> | Recommended | All request parameters, grouped by location |
<Params location="query" /> | Optional | Filter parameters by location (query, header or path) |
<Param name="limit" /> | Optional | Show a single parameter by name |
<Body /> | Recommended | Request body fields and example |
<Field name="email" /> | Optional | Single request body field |
<RequestExamples /> | Recommended | Request examples in multiple languages |
<Responses /> | Recommended | All responses |
<Response code="201" /> | Optional | Single response by code |
<Schema name="User" /> | Optional | Schema definition |
If you use a component with a parameter (e.g. <Param name="user" />), a related object must be defined in the page's frontmatter, otherwise it will not be rendered in the page.
Basic usage
The simplest way to render an API endpoint page is to leave the page content blank. Basedoc will automatically render the endpoint page using this default template:
---
title: "Endpoint name"
api:
# API frontmatter here
---
## Overview
<Endpoint />
## Request parameters
<Params />
## Request body
<Body />
## Request examples
<RequestExamples />
## Responses
<Responses />Advanced usage
You are free to drop in different components to the page to customise the page exactly how you want it.
This is an example of a more custom page, with more specific components.
---
title: "Endpoint name"
api:
# API frontmatter here
---
## Overview
<Endpoint />
## Query parameters
<Params location="query" />
## Headers
<Params location="header" />
## Request body
<Field name="email" />
<Field name="password" />
## Request examples
<RequestExamples />
## Success response
<Response code="200" />
## Error responses
<Response code="400" />
<Response code="404" />
<Response code="500" /><Endpoint> component
This component displays the endpoint method and summary and a copyable URL to the endpoint.
<Params> component
This component displays info about all query, header and path parameters.
If location is defined, only those parameters are displayed.
Accepts the following parameters:
location: The location of the parameters, eitherquery,headerorpath.
<Param> component
This component displays a single query, header or path parameter by name.
Accepts the following parameters:
name: The name of the parameter.location: (optional)The location of the parameter, eitherquery,headerorpath. Use only if you have multiple parameters with the same name.
<Param name="limit" /><Field> component
This component displays a single request body or response body field by name.
Accepts the following parameters:
name: The name of the field.
<Field name="email" /><RequestExamples> component
This component displays a range of code examples for using the API endpoint in different languages.
These examples are auto-generated based on the endpoint definitions, and really useful for your users to help implement your API.
<Responses> component
This component displays all the response types, listing body fields and a schema or code example.
<Response> component
This component displays a single response by code, listing body fields and a schema or code example.
Accepts the following parameters:
code: The HTTP status code of the response.
<Response code="200" />