Last updated

openapi

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

Options

OptionTypeDescription
codeSamples[Language object]Configure the generated code samples in your API documentation.
corsProxyUrlstringSpecifies custom CORS proxy server.
downloadUrlsAPI description URL objectSet 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
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 | string | 'all'Sets the default expand level for JSON payload samples.
layout'three-panel' | 'stacked'Specifies layout options for OpenAPI documentation.
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 | string | 'all'Sets the default expand level for schemas.
showExtensionsstring[] | booleanDisplays specification extensions ('x-' fields).
sortRequiredPropsFirstbooleanSorts schema properties to display required properties first.
feedbackobjectFeedback options.

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 file
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

Resources