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. Supported in Redoc CE.
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. Supported in Redoc CE.
hideDownloadButtonsbooleanToggle the appearance of a Download OpenAPI description section. Supported in Redoc CE.
hideInfoMetadatabooleanToggle the appearance of OpenAPI info metadata sections.
hidePropertiesPrefixbooleanHides the parent name for nested properties. Supported in Redoc CE.
hideReplaybooleanHides the Replay (Try it) functionality.
hideSchemaTitlesbooleanHides the schema field title next to the type. Supported in Redoc CE.
jsonSamplesExpandLevelnumber | stringSets the default expand level for JSON payload samples. Use all to expand all levels. Supported in Redoc CE.
layoutstringSpecifies layout options for OpenAPI documentation. Possible values: three-panel | stacked. Default value: three-panel. Supported in Redoc CE.
maxDisplayedEnumValuesnumberSpecifies number of enum values to display. Supported in Redoc CE.
onlyRequiredInSamplesbooleanDisplays only required fields in request samples. Supported in Redoc CE.
sanitizebooleanSanitize HTML/Markdown to prevent cross-site scripting (XSS) attacks. Supported in Redoc CE.
schemaDefinitionsTagNamestringSets a schema definitions tag name that is applied to all schemas and displayed in the sidebar navigation. Supported in Redoc CE.
schemasExpansionLevelnumber | stringSets the default expand level for schemas. Use all to expand all levels. Supported in Redoc CE.
showExtensions[string] | booleanDisplays specification extensions ('x-' fields). If a list is provided, only those specification extensions are displayed. Supported in Redoc CE.
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. Supported in Redoc CE.

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