ApiSchema

You can display model definitions from your API schema and render them in your Docusaurus Docs. You'll need to create an .mdx file and import the React Component. Read more here about MDX in Docusaurus.

File format

You cannot import a React component inside a .md file.
Change your file extension to .mdx before importing the React Component.
Read more here about MDX in Docusaurus.

Import

import ApiSchema from '@theme/ApiSchema';

Props

Name	Type	Description
pointer	String	the redoc reference to display in Redoc format
showExample	boolean	(default: false) allow to display example
id	String	When spec not provided, load the spec from docusaurus config. Use first spec if not defined
spec	OpenAPI spec	A JSON content spec to use
themeId	String	redocusaurus theme to use - default to theme-redoc

Examples

Basic example

The pointer prop is passed on to Redoc. It displays here the first element of the redocusaurus configuration.

import ApiSchema from '@theme/ApiSchema';

<ApiSchema pointer="#/components/schemas/Pet" />

id	integer <int64> Pet ID Find more info here
	object Categories this pet belongs to
name required	string The name given to a pet
photoUrls required	Array of strings <url> <= 20 items [ items <url > ] The list of URL to a cute photos featuring pet
friend	object Recursive
	Array of objects (Tag) non-empty Tags attached to the pet
status	string Enum: "available" "pending" "sold" Pet status in the store
petType	string Type of a pet catdogbeecat
huntingSkill required	string Default: "lazy" Enum: "clueless" "lazy" "adventurous" "aggressive" The measured skill for hunting

Display example

import ApiSchema from '@theme/ApiSchema';

<ApiSchema showExample pointer="#/components/schemas/Pet" />

id	integer <int64> Pet ID Find more info here
	object Categories this pet belongs to
name required	string The name given to a pet
photoUrls required	Array of strings <url> <= 20 items [ items <url > ] The list of URL to a cute photos featuring pet
friend	object Recursive
	Array of objects (Tag) non-empty Tags attached to the pet
status	string Enum: "available" "pending" "sold" Pet status in the store
petType	string Type of a pet catdogbeecat
huntingSkill required	string Default: "lazy" Enum: "clueless" "lazy" "adventurous" "aggressive" The measured skill for hunting

Example

catdogbeecat

{

• "id": 0,
• "category": {

  • "id": 0,
  • "name": "string",
  • "sub": {

    • "prop1": "string"

    }

  },
• "name": "Guru",
• "photoUrls": [

  • "string"

  ],
• "friend": { },
• "tags": [

  • {

    • "id": 0,
    • "name": "string"

    }

  ],
• "status": "available",
• "petType": "cat",
• "huntingSkill": "adventurous"

}

Multiple OpenAPI schemas example

If you have multiple APIs loaded with redocusaurus, then it is recommended to add ids to the config so that you can refer them when loading schema models.

docusaurus.config.js

const config = {
  presets: [
    '@docusaurus/preset-classic',
    [
      'redocusaurus',
      {
        openapi: {
          path: 'openapi',
          routeBasePath: '/examples',
        },
        specs: [
          {
            id: 'using-remote-url',
            spec: 'https://redocly.github.io/redoc/openapi.yaml',
            route: '/examples/using-remote-url/',
          },
        ],
        [...]
      },
    ],
  ],
};

import ApiSchema from '@theme/ApiSchema';

<ApiSchema id="using-single-yaml" pointer="#/components/schemas/Pet" />
<ApiSchema id="using-remote-url" pointer="#/components/schemas/Order" />

Results for ID id="using-single-yaml"

id	integer <int64> Pet ID Find more info here
	object Categories this pet belongs to
name required	string The name given to a pet
photoUrls required	Array of strings <url> <= 20 items [ items <url > ] The list of URL to a cute photos featuring pet
friend	object Recursive
	Array of objects (Tag) non-empty Tags attached to the pet
status	string Enum: "available" "pending" "sold" Pet status in the store
petType	string Type of a pet catdogbeecat
huntingSkill required	string Default: "lazy" Enum: "clueless" "lazy" "adventurous" "aggressive" The measured skill for hunting

Results for ID id="using-remote-url"

id	integer <int64> Order ID
petId	integer <int64> Pet ID
quantity	integer <int32> >= 1 Default: 1
shipDate	string <date-time> Estimated ship date
status	string Enum: "placed" "approved" "delivered" Order Status
complete	boolean Default: false Indicates whenever order was completed or not

Webpack loader example

You can provide a JSON spec to the component like this. Webpack will load the file directly, you don't need to use redocusaurus configuration inside docusaurus.config.js.

import ApiSchema from '@theme/ApiSchema';
import openApi from './api-with-examples.json'

<ApiSchema spec={openApi} pointer="#/components/schemas/Pet" />

id	integer <int64> Pet ID Find more info here
	object Categories this pet belongs to
name required	string The name given to a pet
photoUrls required	Array of strings <url> <= 20 items [ items <url > ] Default: [] The list of URL to a cute photos featuring pet
friend	object Recursive
	Array of objects (Tag) non-empty Tags attached to the pet
status	string Enum: "available" "pending" "sold" Pet status in the store
petType	string Type of a pet catdogbeecat
huntingSkill required	string Default: "lazy" Enum: "clueless" "lazy" "adventurous" "aggressive" The measured skill for hunting

YAML support

You cannot load yaml file like this:

import openApi from './api-with-examples.yaml'

Without the right webpack configuration to handle such file format.