ApiSchema

You can display model definitions from your API schema and render them in your Docusaurus Docs.

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';

Examples

Basic example

The pointer prop is passed on to Redoc.

import ApiSchema from '@theme/ApiSchema';

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

Results

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 with "examples"

import ApiSchema from '@theme/ApiSchema';

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

Results

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

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',
      {
        specs: [
          {
            id: 'using-single-yaml',
            spec: 'openapi/single-file/openapi.yaml',
            route: '/examples/using-single-yaml/',
          },
          {
            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

Pass JSON Spec Directly

You can also provide a JSON spec to the component like this. Docusaurus will load the file directly during build time, but the file will not undergo any pre-processing at build time and so some features might be missing.

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.