A guide that explains an endpoint can show the endpoint itself: its parameters, request body, responses, and a Try console. Embed one with the api-operation Markdoc tag:
{% api-operation spec="bookstore" path="/orders" method="post" title="Place an order" /%}Attributes
Section titled “Attributes”| Attribute | Meaning |
|---|---|
spec | Required. The id of an API in apis:. |
path | Required. The path as written in the spec, with its {parameters}. |
method | get (default), post, put, patch, delete, ... |
title | A heading for the embed. Default: the operation's summary. |
version | One of the API's versions. Default: its default version. |
An unknown spec id shows a notice on the page and a build warning, so a typo doesn't go unnoticed.
How it works
Section titled “How it works”The embed is RapiDoc's <rapi-doc-mini> element showing one operation of the spec. It follows the portal theme and accent color.
Only pages with an embed load the RapiDoc bundle. Other docs pages stay light.
Try from a guide
Section titled “Try from a guide”Try sends a real request to the spec's server. In this site's example spec, the server is the local mock: run npm run mock in the rapi-portal-doc repository and the console above answers. See Mock server.
With sign-in and auth.tryIt, the embed fills in the signed-in reader's access token. See Try with the reader's token.
In MDX or Markdown
Section titled “In MDX or Markdown”The tag is Markdoc only. In an .md or .mdx guide, link to the operation on its reference page instead: /apis/bookstore/orders#create-order.