Inside of siteConfig.yaml, declare of all of your API definitions.\nThe definition may be in a multi-file format or already bundled. It may be in JSON or YAML format.
You'll use the key name for further reference within the developer portal.
\noasDefinitions:\n acme: ./openapi/acme.yamlThe value may also be a remote URL:
\noasDefinitions:\n acme: https://example.com/acme.yamlAnd an API registry URL:
\noasDefinitions:\n acme: https://api.redoc.ly/registry/testing_acme/adam-api/1.0/bundle/main/openapi.yamlThe benefit of using the API registry (if you use your production \"latest\" snapshot URL) is that the developer portal will rebuild when that API is updated.\nYour docs won't be outdated.
\nIf you use a private registry URL, you will need to use the openapi login command to log in for local development.
\nYou can also declare multiple API definitions:
\noasDefinitions:\n acme: https://api.redoc.ly/registry/testing_acme/adam-api/1.0/bundle/main/openapi.yaml\n acme-v2: https://api.redoc.ly/registry/testing_acme/adam-api/2.0/bundle/main/openapi.yaml\n my-api: https://api.redoc.ly/registry/testing_acme/my-api/1.0.0/bundle/main-branch/openapi.yamlManually create a file reference.page.yaml (you may name it differently, but it must have the .page.yaml file extension) with the following example contents:
type: reference-docs\ndefinitionId: acme\nsettings:\n jsonSampleExpandLevel: alltype: reference-docs\nversions:\n - definitionId: acme\n id: v1\n title: Acme V1\n isDefault: false\n - definitionId: acme-v2\n id: v2\n title: Acme V2\n isDefault: true\n\nsettings:\n jsonSampleExpandLevel: allSupported fields in .page.yaml files
| Field | \nDescription | \n
|---|---|
type | \nMust be set to reference-docs. This field is required. | \n
definitionId | \nReferences the key(s) declared in the siteConfig.yaml. In this example, acme is declared as the key. Do not declare the definitionId if you declare versions. | \n
versions | \nIf the API has multiple versions and you want a version selector to appear then define versions instead of definitionId. The versions is an array with one node per version. Each node must contain a definitionId. It may also contain an id, title, and isDefault value.The id is used in the URL path segment (if not defined it will default to the definitionId value.The title is used in the select menu to display to the user (if not defined it will default to the definitionId.The isDefault will be the version that is pre-selected (if not defined it will default to the first defined version).The select menu will be ordered in the same way as the versions array. | \n
label | \n(optional) Define a custom label to use as the title for the API Overview page in the portal sidebar. If not defined, the value of info.title from the API definition is used by default. | \n
settings | \n(optional) Add any of Redocly's settings to this object. | \n
The location of the page.yaml file determines the URL path segment(s) for the API reference.\nA file such as /openapi/foo.page.yaml will be displayed at /openapi/foo/.
Your integrated Reference docs can optionally use pagination. The configuration settings and the behavior of this functionality are compatible with standalone Reference docs, ensuring a consistent user experience.
\nThe following pagination modes are supported:
\nnone\n - no pagination. All content is displayed as one continuously scrolling page.\nsection\n - each section is displayed as its own page. Tags and tag groups are treated as sections, so all operations grouped under one tag would be displayed on one page. In this mode, tag description text is displayed on the section page together with the operations. Every page automatically gets a \nNext to...\n navigation button at the bottom.\nitem\n - each operation is displayed as its own page, regardless of tags and grouping. In this mode, tag description text is displayed on its own separate page. If a tag doesn't have a description, selecting the tag in the sidebar expands the group to show operations under it. Every page automatically gets a \nNext to...\n navigation button at the bottom.\nTo enable pagination, add any of the modes to the settings section of the .page.yaml file:
type: reference-docs\ndefinitionId: acme\nsettings:\n pagination: section\n showConsole: trueWhen enabled, pagination settings apply to all versions defined in the .page.yaml file.
Keep in mind that:
\nsection\n and \nitem\n modes).\ninfo.description\n field of the API definition always behaves like a section. In \nitem\n mode, it is displayed all on one page, instead of split into separate pages.\nWe strongly recommend you rebuild the portal after modifying pagination settings to avoid potential caching issues.
API overview page
\nBy default, your integrated Reference docs will have an API overview page. This page contains basic information about the API generated from the info object in your API definition (the same as in standalone Reference docs).
To hide the entire API overview page, set hideInfoSection to true:
type: reference-docs\ndefinitionId: acme\nsettings:\n hideInfoSection: trueTo hide only the download button on the API overview page, set hideDownloadButton to true:
type: reference-docs\ndefinitionId: acme\nsettings:\n hideDownloadButton: trueWhen you add Reference docs to the portal sidebar, the API overview page is automatically included as its own sidebar item. It uses the info.title value from the API definition as the item name. You can override this by defining a custom label in the .page.yaml file:
type: reference-docs\ndefinitionId: acme\nlabel: ACME Docs Overview\nsettings:\n pagination: section\n showConsole: trueMarkdown descriptions
\nBy default, all Markdown text from the info.description field of your API definition is visible in the integrated Reference docs. To hide it, set hideInfoDescription to true:
type: reference-docs\ndefinitionId: acme\nsettings:\n hideInfoDescription: trueThis will keep other information from the info section in your Reference docs (such as externalDocs, version and the download button) while hiding all Markdown from info.description.
Authentication
\nBy default, an authentication section is added to your info.description and displayed in integrated Reference docs. To hide it, set noAutoAuth to true:
type: reference-docs\ndefinitionId: acme\nsettings:\n noAutoAuth: trueIf you hide the info section by setting hideInfoSection: true, links to the authentication section from other parts of the documentation are automatically disabled, since there is no target content for them to link to.
Here is an example snippet within the sidebars.yaml:
pages:\n - page: reference.page.yamlpages:\n - page: reference.page.yaml/*pages:\n - page: reference.page.yaml#operation/createUsersWithArrayInputThe first example \"All operations (grouped)\" puts the API in the sidebar inside of a group labeled with the name of the API.
\nThe second example \"All operations (wildcard without the group)\" puts the API in the sidebar without any explicit group. You may define a group if you wish in the sidebars.yaml.
\nThe third example \"Single operation\" puts a single operation into the sidebar.
\nKeep in mind, any given operation can only be referenced once within the sidebars. A sidebar with both reference.page.yaml and reference.page.yaml#operation/createUsersWithArrayInput would have a conflict because the createUsersWithArrayInput operation is already included in the reference.page.yaml.
When you have declared your API definitions, you can use their definitionId with React components to display API reference docs in MDX pages. Pointers allow you to target and display specific parts of the API documentation.
The following components work with API reference docs:
\nThey are supported by default in the portal. You can also develop your own components.
\nTo display API reference docs in an .mdx file, first import the React component, such as OpenApiResponse:
import { OpenApiResponse } from \"@redocly/developer-portal/ui\";Then you can use it as follows:
\nWith code samples panel
\n<OpenApiResponse\n definitionId=\"acme\"\n pointer=\"#/components/responses/CoyoteResponse\"\n/>Without code samples panel
\n<OpenApiResponse\n definitionId=\"acme\"\n pointer=\"#/components/responses/CoyoteResponse\"\n hideSamples=\"{true}\"\n/>