{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"advanced-api-docs-integration","__idx":0},"children":["Advanced API docs integration"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/guides/reference-docs-integration"},"children":["quick integration with OpenAPI files"]},", the developer portal supports an advanced approach for integrating API docs into the portal with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," files."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This approach is required if you want to document multi-version APIs, restrict access to content with RBAC, or integrate API definitions from Redocly API registry without using the API catalog."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-declare-your-api-definitions","__idx":1},"children":["Step 1: Declare your API definition(s)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Declare one or more API definitions in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["oasDefinitions"]}," section at the top level of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]}," file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your API definition could be in a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/learn/openapi/multi-file-definitions"},"children":["multi-file format"]}," or already bundled to a single file. JSON and YAML are both supported, but we use YAML in examples throughout this guide."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Declare the API definition in the following format:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId: target"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]}," can be any custom name of your choice. You use this name to refer to your API definition in the developer portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can provide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["target"]}," in any of the following ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A path to the API definition root file in the developer portal project"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"oasDefinitions:\n  acme: ./openapi/acme.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A remote URL"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"oasDefinitions:\n  acme: https://example.com/acme.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Redocly API ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-registry/guides/snapshots"},"children":["registry snapshot URL"]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"oasDefinitions:\n  acme: https://api.redoc.ly/registry/testing_acme/bundle/adam-api/1.0/main/openapi.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The benefit of linking to the API registry if you use the \"latest\" production snapshot URL is that the developer portal rebuilds when that API is updated, so your docs are not outdated."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you use a private registry URL, you need to use the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/commands/login"},"children":["openapi login command"]}," to log in for local development."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"declare-multiple-apis","__idx":2},"children":["Declare multiple APIs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can declare multiple API definitions at once, and use any of the supported link types for each of the definitions. Every API definition must have a unique name (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]},")."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"oasDefinitions:\n  acme: ./openapi/acme.yaml\n  acme-v2: https://api.redoc.ly/registry/testing_acme/bundle/adam-api/2.0/main/openapi.yaml\n  my-api: https://api.redoc.ly/registry/testing_acme/bundle/my-api/1.0.0/develop/openapi.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-add-pages-that-reference-the-definitions","__idx":3},"children":["Step 2: Add pages that reference the definitions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Manually create a file ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference.page.yaml"]}," in your portal project. You can name the file differently, but it ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," have the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," extension. Use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file to configure the behavior of integrated API docs like in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:\n  jsonSampleExpandLevel: 'all'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: 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: 'all'\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"supported-fields-in-pageyaml-files","__idx":4},"children":["Supported fields in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," files"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["Required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Specifies the configuration file type. Must be set to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference-docs"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["References the key (API definition name) declared in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["siteConfig.yaml"]},". In the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Single API"]}," example above, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acme"]}," is declared as the key. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]}," field accepts only one value per each ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file, so if you want to include multiple versions of an API, use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versions"]}," option instead."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required but mutually exclusive with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versions"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If the API has multiple versions and you want a version switcher to appear in the API documentation, then define ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versions"]}," instead of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versions"]}," is an array with one node per version. Each node must contain a unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]},". It may also contain an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isDefault"]}," value.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," is used in the URL path segment and must be a unique value as well (if not defined, defaults to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]}," value).",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," is used in the version switcher menu as the API display name (if not defined, defaults to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]}," value).",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isDefault"]}," is the version that is pre-selected (if not defined, defaults to the first version listed in the file).",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"The contents of the version switcher menu are ordered in the same way as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versions"]}," array."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required but mutually exclusive with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["definitionId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Defines a custom label to use as the title for the API Overview page in the portal sidebar. If not defined, the value of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.title"]}," from the API definition is used by default."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["excludeFromSearch"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["If set to true, it is excluded from search results and the sitemap. Default value is false."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Can be used to define the permission with ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/configuration/rbac"},"children":["role-based access controls"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settings"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Add any of ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/configuration/functionality"},"children":["Redocly's feature.openapi options"]}," to this object."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"set-up-pagination-for-integrated-api-docs","__idx":5},"children":["Set up pagination for integrated API docs"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your integrated API docs can optionally use pagination. The configuration settings and the behavior of this functionality are compatible with standalone API docs, ensuring a consistent user experience."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following pagination modes are supported:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["none"]}," - no pagination. All content is displayed as one continuously scrolling page. This is the default pagination setting."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["section"]}," - each section is displayed as its own page. Tags and tag groups are treated as sections, so all operations grouped under one tag are displayed on one page. Operations without any tags are not supported in this mode, and pagination does not work for such operations. In this mode, tag description text is displayed on the section page together with the operations. Every page automatically gets a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next to..."]}," navigation button at the bottom."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item"]}," - 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 ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Next to..."]}," navigation button at the bottom."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To enable pagination, add any of the modes to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settings"]}," section of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:\n  pagination: section\n  showConsole: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file has multiple versions defined, the same pagination settings apply to all versions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep in mind that:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["data models always render as separate pages (in both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["section"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item"]}," modes)."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdown text from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.description"]}," field of the API definition always behaves like a section. In ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item"]}," mode, it is displayed all on one page, instead of split into separate pages."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We strongly recommend you rebuild the portal after modifying pagination settings to avoid potential caching issues."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"show-or-hide-content-in-integrated-api-docs","__idx":6},"children":["Show or hide content in integrated API docs"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"api-overview-page","__idx":7},"children":["API overview page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, your integrated docs have an API overview page. This page contains basic information about the API generated from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," object in your API definition (the same as in standalone API docs)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To hide the entire API overview page, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hideInfoSection"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:\n  hideInfoSection: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To hide only the download button on the API overview page, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hideDownloadButton"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:\n  hideDownloadButton: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you add API docs to the portal sidebar, the API overview page is automatically included as its own sidebar item. It uses the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.title"]}," value from the API definition as the item name. You can override this by defining a custom ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nlabel: ACME Docs Overview\nsettings:\n  pagination: section\n  showConsole: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"markdown-descriptions","__idx":8},"children":["Markdown descriptions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, all Markdown text from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.description"]}," field of your API definition is visible in the integrated API docs. To hide it, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hideInfoDescription"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:reference\n  hideInfoDescription: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hideInfoDesciption"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," keeps other information from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," section in your API docs (such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalDocs"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," and the download button) while hiding all Markdown from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.description"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"authentication","__idx":9},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, an authentication section is added to your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info.description"]}," and displayed in integrated API docs. To hide it, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["noAutoAuth"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:\n  noAutoAuth: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you hide the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["info"]}," section by setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"next-to-button","__idx":10},"children":["\"Next to\" button"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you configure ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: section"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: item"]}," for your integrated API docs, all pages automatically get a \"Next to...\" navigation button at the bottom."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To hide this button, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["showNextButton"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"type: reference-docs\ndefinitionId: acme\nsettings:\n  showNextButton: false\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-include-the-pages-in-the-sidebar-or-other-places","__idx":11},"children":["Step 3: Include the pages in the sidebar (or other places)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To make sure your integrated API docs are accessible from the portal sidebar, link to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file within ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can add the API docs page to the sidebar in any of the following ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a plain file link to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file. All operations from your API definition are included in the sidebar as a group, and the group is labeled with the API name."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a \"wildcard\" link to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acme.page.yaml/*"]},"). This adds all operations from your API definition to the sidebar without any explicit grouping. However, some operations may be automatically grouped if your API definition uses tags. You may define a group in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file manually."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As a link to a specific operation or tag in your API definition. This creates a link to a single operation or tag in the sidebar. You can link to an operation by targeting its ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}," (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference.page.yaml#operation/exampleOperation"]},") if ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: item"]}," is set in the referenced ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file. To link to a tag, you must target its name (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference.page.yaml#tag/exampletag"]},") and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: section"]}," must be set in the referenced ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".page.yaml"]}," file."]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["An operation can only be referenced once within the sidebars. A sidebar with both ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference.page.yaml"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference.page.yaml#operation/createUsersWithArrayInput"]}," would have a conflict because the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["createUsersWithArrayInput"]}," operation is already included in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference.page.yaml"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following examples illustrate different ways to include API docs pages in the sidebar."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- group: Reference docs\n  pages:\n    - page: reference.page.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- group: Reference docs\n  pages:\n    - page: reference.page.yaml/*\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- group: Reference docs\n  pages:\n    - page: reference.page.yaml#operation/createUsersWithArrayInput\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following tables illustrate the behavior of integrated API docs depending on the pagination, API definition tags, and sidebar link types."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: none"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tags"},"children":["Tags"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sidebar file link"},"children":["Sidebar file link"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sidebar wildcard link"},"children":["Sidebar wildcard link"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tag link format"},"children":["Tag link format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation link format"},"children":["Operation link format"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One top-level sidebar item as the main group. Every tag is a subgroup with operations under it. Tags have their own links but are not separated from operations. All operations are on a single continuous page."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every tag is a top-level sidebar item with operations grouped under it. Tags have their own links but are not separated from operations. All operations are on a single continuous page."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/#tag/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagName"]},"/"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/#operation/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One top-level sidebar item with all operations under it. All operations are on a single continuous page."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every operation is a top-level sidebar item. All operations are on a single continuous page."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/#operation/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: section"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tags"},"children":["Tags"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sidebar file link"},"children":["Sidebar file link"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sidebar wildcard link"},"children":["Sidebar wildcard link"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tag link format"},"children":["Tag link format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation link format"},"children":["Operation link format"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One top-level sidebar item as the main group. Every tag is a subgroup with operations under it. Tags have their own links but are not separated from operations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every tag is a top-level sidebar item with operations grouped under it. Tags have their own links but are not separated from operations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/tag/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagName"]},"/"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/tag/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagName"]},"/#tag/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagName"]},"/operation/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not supported - sidebar links don't work."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not supported - sidebar links don't work."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not supported"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagination: item"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tags"},"children":["Tags"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sidebar file link"},"children":["Sidebar file link"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Sidebar wildcard link"},"children":["Sidebar wildcard link"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tag link format"},"children":["Tag link format"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation link format"},"children":["Operation link format"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tags with descriptions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One top-level sidebar item as the main group. Every tag is a subgroup with operations under it. A tag and its description have their own link and page separate from operations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every tag is a top-level sidebar item with operations grouped under it. A tag and its description have their own link and page separate from operations."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/tag/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tagName"]},"/"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/operation/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]},"/"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tags without descriptions"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One top-level sidebar item as the main group. Every tag is a subgroup with operations under it. Tags don't have their own links or pages, and just expand when clicked."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every tag is a top-level sidebar item with operations grouped under it. Tags don't have their own links or pages, and just expand when clicked."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/operation/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No tags"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One top-level sidebar item with all operations under it. Every operation is on its own page."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Every operation is a top-level sidebar item and has its own page."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["None"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reference"]},"/operation/",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["operationId"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-4-render-api-docs-in-mdx-pages","__idx":12},"children":["Step 4: Render API docs in MDX pages"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you have declared your API definitions, you can use their ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following components work with API reference docs:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["They are supported by default in the portal. You can also develop your own components."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To display API reference docs in an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".md"]}," file:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Import the React component, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OpenApiResponse"]},":"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"jsx","header":{"controls":{"copy":{}}},"source":"import { OpenApiResponse } from '@redocly/developer-portal/ui';\n","lang":"jsx"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use it as follows:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["With code samples panel"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<OpenApiResponse definitionId=\"acme\" pointer=\"#/components/responses/CoyoteResponse\" />\n","lang":"html"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Without code samples panel"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"html","header":{"controls":{"copy":{}}},"source":"<OpenApiResponse definitionId=\"acme\" pointer=\"#/components/responses/CoyoteResponse\" hideSamples={true} />\n","lang":"html"},"children":[]}]},"frontmatter":{"excludeFromSearch":true},"tagList":["admonition","html","partial"],"title":"Advanced API docs integration","lastModified":"2025-05-28T16:01:32.000Z"}