# `openapi`

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

## Options

| Option | Type | Description |
|  --- | --- | --- |
| [codeSamples](/docs/realm/config/openapi/code-samples) | [[Language object](/docs/realm/config/openapi/code-samples#language-object)] | Configure the generated code samples in your API documentation. |
| [corsProxyUrl](/docs/realm/config/openapi/cors-proxy-url) | string | Specifies custom CORS proxy server. |
| [downloadUrls](/docs/realm/config/openapi/download-urls) | [API description URL object](/docs/realm/config/openapi/download-urls#api-description-url-object) | Set the URLs used to download the API description in JSON or YAML format. |
| [events](/docs/realm/config/openapi/events) | object | Event 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](#exclude-an-api-from-search), or to [all OpenAPI descriptions](#exclude-all-apis-from-search).
 |
| feedback | [Feedback object](/docs/realm/config/feedback#options) | Hide or customize the type of or text included in the feedback form that displays at the end of each endpoint. |
| [generatedSamplesMaxDepth](/docs/realm/config/openapi/generated-samples-max-depth) | number | Sets the number of levels to display in generated payload samples. |
| [hideDownloadButtons](/docs/realm/config/openapi/hide-download-buttons) | boolean | Toggle the appearance of a **Download OpenAPI description** section. |
| [hideInfoMetadata](/docs/realm/config/openapi/hide-info-metadata) | boolean | Toggle the appearance of **OpenAPI info metadata** sections. |
| [hidePropertiesPrefix](/docs/realm/config/openapi/hide-properties-prefix) | boolean | Hides the parent name for nested properties. |
| [hideReplay](/docs/realm/config/openapi/hide-replay) | boolean | Hides the Replay (Try it) functionality. |
| [hideSchemaTitles](/docs/realm/config/openapi/hide-schema-titles) | boolean | Hides the schema field title next to the type. |
| [jsonSamplesExpandLevel](/docs/realm/config/openapi/json-samples-expand-level) | number | string | 'all' | Sets the default expand level for JSON payload samples. |
| [layout](/docs/realm/config/openapi/layout) | 'three-panel' | 'stacked' | Specifies layout options for OpenAPI documentation. |
| [maxDisplayedEnumValues](/docs/realm/config/openapi/max-displayed-enum-values) | number | Specifies number of enum values to display. |
| [onlyRequiredInSamples](/docs/realm/config/openapi/only-required-in-samples) | boolean | Displays only required fields in request samples. |
| [sanitize](/docs/realm/config/openapi/sanitize) | boolean | Sanitize HTML/Markdown to prevent [cross-site scripting (XSS)](https://owasp.org/www-community/attacks/xss/) attacks. |
| [schemaDefinitionsTagName](/docs/realm/config/openapi/schema-definitions-tag-name) | string | Sets a schema definitions tag name that is applied to all schemas and displayed in the sidebar navigation. |
| [schemasExpansionLevel](/docs/realm/config/openapi/schemas-expansion-level) | number | string | 'all' | Sets the default expand level for schemas. |
| [showExtensions](/docs/realm/config/openapi/show-extensions) | string[] | boolean | Displays specification extensions ('x-' fields). |
| [sortRequiredPropsFirst](/docs/realm/config/openapi/sort-required-props-first) | boolean | Sorts schema properties to display required properties first. |
| [feedback](/docs/realm/config/feedback#options) | object | Feedback 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:


```yaml 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
```

### Exclude an API from search

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`.


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

### Exclude all APIs from search

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


```yaml redocly.yaml
openapi:
  excludeFromSearch: true
```

## Resources

- **[OpenAPI Specification](https://spec.openapis.org/oas/latest.html)** - Official OpenAPI Specification documentation for understanding API description standards and best practices
- **[Migration guide](/docs/realm/config/openapi/config-migration)** - Migrate from reference docs 2.x to the newest Redoc configuration for updated features and functionality
- **[Configuration options](/docs/realm/config)** - Explore other project configuration options for comprehensive documentation and platform customization