Skip to content
Last updated

openapi

Products:RedocRedocRealmRealm
Plans:ProEnterpriseEnterprise+

Customize the behavior and appearance of integrated API documentation. Requires an OpenAPI description.

Options

OptionTypeDescription
codeSamplesCode Samples objectConfigure the generated code samples in your API documentation.
corsProxyUrlstringSpecifies custom CORS proxy server.
downloadUrls[API description URL object]List the URLs used to download the API description in JSON or YAML format.
eventsobjectEvent hooks to get notified about various user events in API docs

excludeFromSearch

boolean

Excludes an OpenAPI description file from search results and llms.txt when set to true. Default: false.

You can apply it to a specific files, or to all OpenAPI descriptions.

feedbackFeedback objectHide or customize the type of or text included in the feedback form that displays at the end of each endpoint.
generatedSamplesMaxDepthnumberSets the number of levels to display in generated payload samples.
hideDownloadButtonsbooleanToggle the appearance of a Download OpenAPI description section.
hideInfoMetadatabooleanToggle the appearance of OpenAPI info metadata sections.
hidePropertiesPrefixbooleanHides the parent name for nested properties.
hideReplaybooleanHides the Replay (Try it) functionality.
hideSchemaTitlesbooleanHides the schema field title next to the type.
jsonSamplesExpandLevelnumber | stringSets the default expand level for JSON payload samples. Use all to expand all levels.
layoutstringSpecifies layout options for OpenAPI documentation. Possible values: three-panel | stacked. Default value: three-panel.
maxDisplayedEnumValuesnumberSpecifies number of enum values to display.
onlyRequiredInSamplesbooleanDisplays only required fields in request samples.
sanitizebooleanSanitize HTML/Markdown to prevent cross-site scripting (XSS) attacks.
schemaDefinitionsTagNamestringSets a schema definitions tag name that is applied to all schemas and displayed in the sidebar navigation.
schemasExpansionLevelnumber | stringSets the default expand level for schemas. Use all to expand all levels.
showExtensions[string] | booleanDisplays specification extensions ('x-' fields). If a list is provided, only those specification extensions are displayed.
showSchemaCatalogLinksbooleanDisplays links to schemas and requests on an OpenAPI page. These links can be used as $ref value in other OpenAPI files within the same project. Default value: false.
sortRequiredPropsFirstbooleanSorts schema properties to display required properties first.

Examples

Configure multiple APIs

In your config file, the openapi options can be defined in the root-level or per-API.

  • Root-level options apply to all API descriptions.
  • API-level options apply only to individual descriptions.
  • If both are present, then the options are merged, but the per-API options take precedence.

The following example shows separate configurations for multiple APIs:

redocly.yaml
logo: images/awesome-logo.svg
openapi:
  hideReplay: true
apis:
  museum@default:
    root: 'openapi/museum.yaml'
    openapi:
      downloadUrls:
        - title: Download OpenApiDescription
          url: 'https://github.com/Redocly/museum-openapi-example/blob/main/openapi.yaml'
      hideReplay: false
      codeSamples:
        languages:
          - lang: 'curl'
            label: 'curl'
      hideRequestPayloadSample: true
  museum@test:
    root: 'openapi/museum-test.yaml'
    openapi:
      hideDownloadButtons: true
      hideReplay: true
      codeSamples:
        languages:
          - lang: 'Node.js'
          - lang: 'go'
rules:
  example-rule-name: error

To exclude a specific API from the search results, locate the API in redocly.yaml and under the openapi key, set the excludeFromSearch option to true.

redocly.yaml
apis:
  museum@default:
    root: 'openapi/redocly-museum.yaml'
    openapi:
      excludeFromSearch: true

To exclude all APIs from the search results, under the openapi key, set the excludeFromSearch option to true.

redocly.yaml
openapi:
  excludeFromSearch: true

Resources

  • OpenAPI Specification - Official OpenAPI Specification documentation for understanding API description standards and best practices
  • Migration guide - Migrate from reference docs 2.x to the newest Redoc configuration for updated features and functionality
  • Configuration options - Explore other project configuration options for comprehensive documentation and platform customization
 
Next page