redoc Documentation

1. Project Overview & Quickstart (Redocly/redoc) Copy Chapter

File: README.md Copy Chapter

About Redoc Copy Chapter

Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions.

By default Redoc offers a three-panel, responsive layout:

• The left panel contains a search bar and navigation menu.
• The central panel contains the documentation.
• The right panel contains request and response examples.

Live demo Copy Chapter

If you want to see how Redoc renders your OpenAPI definition,
you can try it out online at https://redocly.github.io/redoc/.

A version of the Swagger Petstore API is displayed by default.
To test it with your own OpenAPI definition,
enter the URL for your definition and select TRY IT.

Redoc features Copy Chapter

• Responsive three-panel design with menu/scrolling synchronization
• Support for OpenAPI 3.1, OpenAPI 3.0, and Swagger 2.0
• Ability to integrate your API introduction into the side menu
• High-level grouping in side menu with the x-tagGroups specification extension
• Simple integration with create-react-app
• Code samples support (with vendor extension)

Usage Copy Chapter

Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component.

Generate documentation from the CLI Copy Section

If you have Node installed, quickly generate documentation using npx:

npx @redocly/cli build-docs openapi.yaml

The tool outputs by default to a file named redoc-static.html that you can open in your browser.

Redocly CLI does more than docs; check it out and add linting, bundling, and more to your API workflow.

Add an HTML element to the page Copy Section

Create an HTML page, or edit an existing one, and add the following within the body tags:

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>

Open the HTML file in your browser, and your API documentation is shown on the page.

Add your own spec-url to the <redoc> tag; this attribute can also be a local file. The JavaScript library can also be installed locally using npm and served from your own server, see the HTML deployment documentation for more details.

More usage options Copy Section

Check out the deployment documentation for more options, and detailed documentation for each.

Redoc vs hosted Redoc Copy Chapter

Redoc is Redocly's community-edition product. Looking for something more?
We also offer a hosted Redoc
with additional features including:

• Try-it console
• Automated code samples
• Fully custom styles
• Mock server
• AsyncAPI
• GraphQL

Documentation and resources Copy Section

• Realm - we take care of the hosting
• Redoc - detailed documentation for this open source project (also in the docs/ folder)
• Command-line interface to bundle your docs into a web-ready HTML file
• API linting, bundling, and much more with open source Redocly CLI

Showcase Copy Chapter

A sample of the organizations using Redocly tools in the wild:

• Rebilly
• Docker Engine
• Zuora
• Discourse
• Commbox
• APIs.guru
• BoxKnight
• Quaderno API

Pull requests to add your own API page to the list are welcome

Configuration Copy Chapter

Redoc is highly configurable, see the configuration documentation for details.

OpenAPI specification extensions Copy Section

Redoc uses the following specification extensions:

• x-logo - is used to specify API logo
• x-traitTag - useful for tags that refer to non-navigation properties like Pagination, Rate-Limits, etc
• x-codeSamples - specify operation code samples
• x-badges - specify operation badges
• x-examples - specify JSON example for requests
• x-nullable - mark schema param as a nullable
• x-displayName - specify human-friendly names for the menu categories
• x-tagGroups - group tags by categories in the side menu
• x-servers - ability to specify different servers for API (backported from OpenAPI 3.0)
• x-additionalPropertiesName - ability to supply a descriptive name for the additional property keys
• x-summary - for Response object, use as the response button text, with description rendered under the button
• x-explicitMappingOnly - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object

Releases Copy Chapter

The README for the 1.x version is on the v1.x branch.

All the 2.x releases are deployed to npm and can be used with Redocly-cdn:

• particular release, for example, v2.0.0: https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.js
• latest release: https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js

Additionally, all the 1.x releases are hosted on our GitHub Pages-based CDN (deprecated):

• particular release, for example v1.2.0: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.js
• v1.x.x release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.js
• latest release: https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js - points to latest 1.x.x release since 2.x releases are not hosted on this CDN but on unpkg.

Development Copy Chapter

see CONTRIBUTING.md

File: config/docker/README.md Copy Chapter

Official ReDoc Docker Image

Usage Copy Chapter

Docker Copy Section

Serve remote spec by URL:

docker run -it --rm -p 80:80 \
  -e SPEC_URL='http://localhost:8000/swagger.yaml' redocly/redoc

Serve local file:

docker run -it --rm -p 80:80 \
  -v $(pwd)/demo/swagger.yaml:/usr/share/nginx/html/swagger.yaml \
  -e SPEC_URL=swagger.yaml redocly/redoc

Serve local file and watch for updates:

docker run -it --rm -p 80:80 \
  -v $(pwd)/demo/:/usr/share/nginx/html/swagger/ \
  -e SPEC_URL=swagger/swagger.yaml redocly/redoc

OpenShift Copy Section

To quote OpenShift Container Platform-Specific Guidelines:

Support Arbitrary User IDs

By default, OpenShift Container Platform runs containers using an arbitrarily assigned user ID. This provides additional security against processes escaping the container due to a container engine vulnerability and thereby achieving escalated permissions on the host node.

For an image to support running as an arbitrary user, directories and files that may be written to by processes in the image should be owned by the root group and be read/writable by that group. Files to be executed should also have group execute permissions.

To comply with those requirements the Dockerfile contains instructions to adapt the rights for the folders:

• /etc/nginx because the docker-run.sh script modifies it at startup time
• /usr/share/nginx/html because the docker-run.sh script modifies it at startup time
• /var/cache/nginx because the Nginx process writes to it
• /var/log/nginx because the Nginx process writes to it
• /var/run because the Nginx process writes to it

Another issue with OpenShift is that the default exposed port 80 cannot be used as it is restricted. So one needs to use another port like 8080 (using the PORT configuration as described below), and then to configure the container spec accordingly.

Runtime configuration options Copy Chapter

• PAGE_TITLE (default "ReDoc") - page title
• PAGE_FAVICON (default "favicon.png") - URL to page favicon
• BASE_PATH (optional) - prepend favicon & standalone bundle with this path
• SPEC_URL (default "http://petstore.swagger.io/v2/swagger.json") - URL to spec
• PORT (default 80) - nginx port
• REDOC_OPTIONS (optional) - <redoc> tag attributes

Build Copy Chapter

docker build -t redocly/redoc .

File: docs/deployment/cli.md Copy Chapter

seo: title: Use the Redoc CLI Copy Chapter

How to use the Redocly CLI

With Redocly CLI, you can bundle your OpenAPI definition and API documentation
(made with Redoc) into an HTML file and render it locally.

Step 1 - Install Redocly CLI Copy Chapter

First, you need to install the @redocly/cli package.

You can install it globally using npm.

Or you can install it during runtime using npx or Docker.

Step 2 - Build the HTML file Copy Chapter

The Redocly CLI build-docs command builds Redoc into an HTML file.

To build an HTML file using Redocly CLI, enter the following command,
replacing apis/openapi.yaml with your API definition file's name and path:

redocly build-docs apis/openapi.yaml

See the build-docs documentation for more information
on the different options and ways you can use the command.

Also, check out Redocly CLI commands, for more
information on the different things you can do with Redocly CLI including
linting, splitting, and bundling your API definition file.

File: docs/deployment/docker.md Copy Chapter

seo: title: Use the Redoc Docker image Copy Chapter

How to use the Redoc Docker image

Redoc is available as a pre-built Docker image in Docker Hub.

If you have Docker installed, pull the image with the following command:

docker pull redocly/redoc

Then run the image with the following command:

docker run -p 8080:80 redocly/redoc

The preview starts on port 8080, based on the port used in the command,
and can be accessed at http://localhost:8080.
To exit the preview, use control+C.

By default Redoc starts with a demo Swagger Petstore OpenAPI definition located at
http://petstore.swagger.io/v2/swagger.json. You can update this URL using
the environment variable SPEC_URL.

For example:

docker run -p 8080:80 -e SPEC_URL=https://api.example.com/openapi.json redocly/redoc

Create a Dockerfile Copy Chapter

You can also create a Dockerfile with some predefined environment variables. Check out
a sample Dockerfile
in our code repo.

File: docs/deployment/intro.md Copy Chapter

seo: title: Redoc deployment guide Copy Chapter

Redoc deployment guide

Redoc offers multiple options for rendering your OpenAPI definition.
You should select the option that best fits your needs.

The following options are supported:

• Live demo:
  The live demo offers a fast way to see how your OpenAPI renders with Redoc.
  A version of the Swagger Petstore API is displayed by default. To test it with your own OpenAPI definition, enter the URL for your
  definition and select TRY IT.
• HTML element:
  Using the HTML element works well for typical website deployments.
• React component:
  Using the React component is an option for users with a React-based application.
• Docker image:
  Using the Docker image works in a container-based deployment.
• Redocly CLI:
  Using the Redocly CLI is an option for users who prefer to use a command-line interface.

Before you start Copy Chapter

OpenAPI definition Copy Section

You need an OpenAPI definition. For testing purposes, you can use one of the following sample OpenAPI definitions:

• OpenAPI 3.0
  • Museum Example API
  • Petstore Sample OpenAPI Definition
• OpenAPI 2.0
  • Thingful OpenAPI Definition
  • Fitbit Plus OpenAPI Definition

{% admonition type="info" name="OpenAPI specification" %}
For more information on the OpenAPI specification, refer to the Learning OpenAPI 3
section in the documentation.
{% /admonition %}

How to run Redoc locally Copy Section

If you want to view your Redoc output locally, you can simulate an HTTP server.

Python

If you have Python 3 installed, cd into your
project directory and run the following command:

python3 -m http.server

If you have Python 2 installed, cd into your
project directory and run the following command:

python -m SimpleHTTPServer 8000

The output after entering the command provides the local URL where the preview can be accessed.
To exit the preview, use control-C.

Node.js

If you have Node.js installed, install http-server
using the following npm command:

npm install http-server

Then, cd into your project directory and run the following command:

http-server

The output after entering the command provides the local URL where the preview can be accessed.
To exit the preview, use control-C.

File: docs/deployment/react.md Copy Chapter

seo:
title: Use the Redoc React component
redirects:
'/docs/redoc/quickstart/react/':
to: '/docs/redoc/deployment/react/'

How to use the Redoc React component

Before you start Copy Chapter

Install the following dependencies required by Redoc if you do not already have them installed:

• react
• react-dom
• mobx
• styled-components
• core-js

If you have npm installed, you can install these dependencies using the following command:

npm i react react-dom mobx styled-components core-js

Step 1 - Import the `RedocStandalone` component Copy Chapter

import { RedocStandalone } from 'redoc';

Step 2 - Use the component Copy Chapter

You can either link to your OpenAPI definition with a URL, using the following format:

<RedocStandalone specUrl="url/to/your/spec"/>

Or you can pass your OpenAPI definition as an object, using the following format:

<RedocStandalone spec={/* spec as an object */}/>

Optional - Pass options Copy Chapter

Options can be passed into the RedocStandalone component to alter how it renders.

For example:

<RedocStandalone
  specUrl="http://petstore.swagger.io/v2/swagger.json"
  options={{
    nativeScrollbars: true,
    theme: { colors: { primary: { main: '#dd5522' } } },
  }}
/>

For more information on configuration options, refer to the
Configuration options for Reference docs
section of the documentation. Options available for Redoc are noted,
"Supported in Redoc CE".

Optional - Specify `onLoaded` callback Copy Chapter

You can also specify the onLoaded callback, which is called each time Redoc
is fully rendered or when an error occurs (with an error as the first argument).

<RedocStandalone
  specUrl="http://petstore.swagger.io/v2/swagger.json"
  onLoaded={(error) => {
    if (!error) {
      console.log('Yay!');
    }
  }}
/>

File: docs/config.md Copy Chapter

Configure Redoc

Getting your documentation just right is important, and Redoc comes with many configuration options to help you succeed in that mission.

Each deployment type has documentation on how to configure options for that type of Redoc project. This page lists all the options you can use with Redoc.

Versions: 2.x

{% admonition type="success" name="Client-side configuration" %}

Using Redoc as a standalone (HTML or React) tool, these options must be presented in kebab case.
For example, scrollYOffset becomes scroll-y-offset, and expandResponses becomes expand-responses.

{% /admonition %}

Functional settings Copy Chapter

disableSearch Copy Section

Disables search indexing and hides the search box from the API documentation page.

minCharacterLengthToInitSearch Copy Section

Sets the minimum amount of characters that need to be typed into the search dialog to initiate the search.

Default: 3

hideDownloadButtons Copy Section

Hides the 'Download' button for saving the API definition source file. This setting does not make the API definition private; it just hides the button.

hideLoading Copy Section

Hides the loading animation. Does not apply to CLI or Workflows-rendered docs.

hideSchemaTitles Copy Section

Hides the schema title next to to the type.

jsonSamplesExpandLevel Copy Section

Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value all that expands all levels.

Default: 2

maxDisplayedEnumValues Copy Section

Displays only the specified number of enum values. The remaining values are hidden in an expandable area. If not set, all values are displayed.

onlyRequiredInSamples Copy Section

Shows only required fields in request samples.

sortRequiredPropsFirst Copy Section

Shows required properties in schemas first, ordered in the same order as in the required array.

schemasExpansionLevel Copy Section

Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemasExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.

scrollYOffset Copy Section

Specifies a vertical scroll-offset.
This setting is useful when there are fixed positioned elements at the top of the page, such as navbars, headers, etc.

Note that you can specify the scrollYOffset value in any of the following ways:

• as a number - a fixed number of pixels to be used as the offset.
• as a CSS selector - the selector of the element to be used for specifying the offset. The distance from the top of the page to the element's bottom is used as the offset.
• a function (advanced) - a getter function. Must return a number representing the offset (in pixels).

showExtensions Copy Section

Shows specification extensions ('x-' fields). Extensions used by Redoc are ignored. The value can be boolean or an array of strings with names of extensions to display. When used as boolean and set to true, all specification extensions are shown.

sanitize Copy Section

If set to true, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.

downloadUrls Copy Section

Set the URLs used to download the OpenAPI description or other documentation related files from the API documentation page.

schemaDefinitionsTagName Copy Section

If a value is set, all of the schemas are rendered with the designated tag name. The schemas then render and display in the sidebar navigation (with that associated tag name).

generatedSamplesMaxDepth Copy Section

The generatedSamplesMaxDepth option controls how many schema levels automatically generated for payload samples. The default is 8 which works well for most APIs, but you can adjust it if necessary for your use case.

hidePropertiesPrefix Copy Section

In complex data structures or object schemas where properties are nested within parent objects the hidePropertiesPrefix option enables the hiding of parent names for nested properties within the documentation.

Default: true

Deprecated Functional settings Copy Chapter

hideDownloadButton Copy Section

Hides the 'Download' button for saving the API definition source file. This setting does not make the API definition private; it just hides the button.

downloadFileName Copy Section

Sets the filename for the downloaded API definition source file.

downloadDefinitionUrl Copy Section

Sets the URL for the downloaded API definition source file.

requiredPropsFirst Copy Section

Shows required properties in schemas first, ordered in the same order as in the required array.

jsonSampleExpandLevel Copy Section

Sets the default expand level for JSON payload samples (response and request body). The default value is 2, and the maximum supported value is '+Infinity'. It can also be configured as a string with the special value all that expands all levels.

Default: 2

schemaExpansionLevel Copy Section

Specifies whether to automatically expand schemas in Reference docs. Set it to all to expand all schemas regardless of their level, or set it to a number to expand schemas up to the specified level. For example, schemaExpansionLevel: 3 expands schemas up to three levels deep. The default value is 0, meaning no schemas are expanded automatically.

expandDefaultServerVariables Copy Section

Enables or disables expanding default server variables.

expandResponses Copy Section

Controls which responses to expand by default. Specify one or more responses by providing their response codes as a comma-separated list without spaces, for example expandResponses='200,201'. Special value 'all' expands all responses by default. Be careful: this option can slow down documentation rendering time.

expandSingleSchemaField Copy Section

Automatically expands the single field in a schema.

hideHostname Copy Section

If set to true, the protocol and hostname are not shown in the operation definition.

hideRequestPayloadSample Copy Section

Hides request payload examples.

hideOneOfDescription Copy Section

If set to true, the description for oneOf/anyOf object is not shown in the schema.

hideSchemaPattern Copy Section

If set to true, the pattern is not shown in the schema.

hideSecuritySection Copy Section

Hides the Security panel section.

hideSingleRequestSampleTab Copy Section

Hides the request sample tab for requests with only one sample.

menuToggle Copy Section

If set to true, selecting an expanded item in the sidebar twice collapses it.

Default: true

nativeScrollbars Copy Section

If set to true, the sidebar uses the native scrollbar instead of perfect-scroll. This setting is a scrolling performance optimization for big API definitions.

pathInMiddlePanel Copy Section

Shows the path link and HTTP verb in the middle panel instead of the right panel.

payloadSampleIdx Copy Section

If set, the payload sample is inserted at the specified index. If there are N payload samples and the value configured here is bigger than N, the payload sample is inserted last. Indexes start from 0.

showObjectSchemaExamples Copy Section

Shows object schema example in the properties; default false.

showWebhookVerb Copy Section

When set to true, shows the HTTP request method for webhooks in operations and in the sidebar.

simpleOneOfTypeLabel Copy Section

Shows only unique oneOf types in the label without titles.

sortEnumValuesAlphabetically Copy Section

When set to true, sorts all enum values in all schemas alphabetically.

sortOperationsAlphabetically Copy Section

When set to true, sorts operations in the navigation sidebar and in the middle panel alphabetically.

sortPropsAlphabetically Copy Section

When set to true, sorts properties in all schemas alphabetically.

sortTagsAlphabetically Copy Section

When set to true, sorts tags in the navigation sidebar and in the middle panel alphabetically. Note that only tags are sorted alphabetically in the middle panel, not the operations associated with each tag. To sort operations alphabetically as well, you must set the sortOperationsAlphabetically setting to true.

Default: false

untrustedSpec Copy Section

If set to true, the API definition is considered untrusted and all HTML/Markdown is sanitized to prevent XSS.

Theme settings Copy Chapter

Change styles for the API documentation page. Supported in Redoc CE 2.x.

• spacing
  • unit: 5 # main spacing unit used in autocomputed theme values later
  • sectionHorizontal: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
  • sectionVertical: 40 # Horizontal section padding. COMPUTED: spacing.unit * 8
• breakpoints # breakpoints for switching three/two and mobile view layouts
  • small: '50rem'
  • medium: '85rem'
  • large: '105rem'
• colors
  • tonalOffset: 0.3 # default tonal offset used in computations
• typography
  • fontSize: '14px'
  • lineHeight: '1.5em'
  • fontWeightRegular: '400'
  • fontWeightBold: '600'
  • fontWeightLight: '300'
  • fontFamily: 'Roboto, sans-serif'
  • smoothing: 'antialiased'
  • optimizeSpeed: true
  • headings
    • fontFamily: 'Montserrat, sans-serif'
    • fontWeight: '400'
    • lineHeight: '1.6em'
  • code # inline code styling
    • fontSize: '13px'
    • fontFamily: 'Courier, monospace'
    • lineHeight: # COMPUTED: typography.lineHeight
    • fontWeight: # COMPUTED: typography.fontWeightRegular
    • color: '#e53935'
    • backgroundColor: 'rgba(38, 50, 56, 0.05)'
    • wrap: false # whether to break word for inline blocks (otherwise they can overflow)
  • links
    • color: # COMPUTED: colors.primary.main
    • visited: # COMPUTED: typography.links.color
    • hover: # COMPUTED: lighten(0.2 typography.links.color)
    • textDecoration: 'auto'
    • hoverTextDecoration: 'auto'
• sidebar
  • width: '260px'
  • backgroundColor: '#fafafa'
  • textColor: '#333333'
  • activeTextColor: # COMPUTED: theme.sidebar.textColor (if set by user) or theme.colors.primary.main
  • groupItems # Group headings
    • activeBackgroundColor: # COMPUTED: theme.sidebar.backgroundColor
    • activeTextColor: # COMPUTED: theme.sidebar.activeTextColor
    • textTransform: 'uppercase'
  • level1Items # Level 1 items like tags or section 1st level items
    • activeBackgroundColor: # COMPUTED: theme.sidebar.backgroundColor
    • activeTextColor: # COMPUTED: theme.sidebar.activeTextColor
    • textTransform: 'none'
  • arrow # sidebar arrow
    • size: '1.5em'
    • color: # COMPUTED: theme.sidebar.textColor
• logo
  • maxHeight: # COMPUTED: sidebar.width
  • maxWidth: # COMPUTED: sidebar.width
  • gutter: '2px' # logo image padding
• rightPanel
  • backgroundColor: '#263238'
  • width: '40%'
  • textColor: '#ffffff'
  • servers
    • overlay
      • backgroundColor: '#fafafa'
      • textColor: '#263238'
    • url
      • backgroundColor: '#fff'
• fab
  • backgroundColor: '#263238'
  • color: '#ffffff'

Additional customization Copy Chapter

Security Definition location Copy Section

You can inject the Security Definitions widget into any place in your definition description.
For more information, refer to Security definitions injection.

OpenAPI specification extensions Copy Section

Redoc uses the following specification extensions:

• x-logo - is used to specify API logo
• x-traitTag - useful for handling out common things like Pagination, Rate-Limits, etc
• x-codeSamples - specify operation code samples
• x-examples - specify JSON example for requests
• x-nullable - mark schema param as a nullable
• x-displayName - specify human-friendly names for the menu categories
• x-tagGroups - group tags by categories in the side menu
• x-servers - ability to specify different servers for API (backported from OpenAPI 3.0)
• x-additionalPropertiesName - ability to supply a descriptive name for the additional property keys
• x-summary - For Response object, use as the response button text, with description rendered under the button
• x-explicitMappingOnly - In Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an object

File: docs/index.md Copy Chapter

seo: title: Redoc Copy Chapter

Redoc: Open source API documentation tool

Redoc is a clean and easy way to produce web-ready documentation from an OpenAPI description (Swagger is also still supported). With one command, create your documentation, and customize it to meet the needs of your users.

Redoc is based around a three panel layout, with clear sections for navigation, detailed documentation, and request/response examples.

Headline features Copy Chapter

• Modern layout with extensive customization options.
• Support for OpenAPI 3.1, 3.0 and older 2.0 and Swagger formats.
• Embed or build standalone HTML documentation.
• CLI tool for easy automation and local development.

Demo Copy Chapter

Try the live demo and upload your own API specification there to try.

Usage Copy Chapter

Redoc is provided as a CLI tool (also distributed as a Docker image), HTML tag, and React component.

Generate documentation from the CLI Copy Section

If you have Node installed, quickly generate documentation using npx:

npx @redocly/cli build-docs openapi.yaml

The tool outputs by default to a file named redoc-static.html that you can open in your browser.

Redocly CLI does more than docs, check it out and add linting, bundling and more to your API workflow.

Add an HTML element to the page Copy Section

Create an HTML page, or edit an existing one, and add the following:

<redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>

Open the HTML file in your browser, and your API documentation is shown on the page.

Add your own spec-url to the <redoc> tag; this attribute can also be a local file. The JavaScript library can also be installed locally using npm and served from your own server, see the HTML deployment documentation for more details.

More usage options Copy Section

Check out the deployment documentation for more options, and detailed documentation for each.

Configure Redoc Copy Chapter

Redoc is highly configurable. Each deployment option accepts configuration in a way that's appropriate to that platform, but the options are the same for each. For example:

• Using Redocly CLI, configuration goes in the redocly.yaml file, or can be supplied as command line parameters, such as --theme.openapi.disableSearch.
• Using HTML or React, configure by setting option in the tag.

Here's a sample redocly.yaml configuration file, showing a few common settings and tweaking some of the visual theme settings:

theme:
  openapi:
    disableSearch: true
    expandResponses: 200,202
    jsonSamplesExpandLevel: 1

    theme:
      sidebar:
        backgroundColor: '#eae0cc'
        textColor: '#3d005b'
      colors:
        primary:
          main: '#660099'
      typography:
        fontSize: 14pt
        headings:
          fontWeight: bold

Redocly CLI detects a file named redocly.yaml in the same directory as you run the command and uses it. See the documentation with a command like this:

redocly build-docs openapi.yaml

There are many, many more options available. Visit the configuration reference for a complete list.

Next steps Copy Chapter

• If you are new to OpenAPI, try the OpenAPI starter project for a great introduction.
• Ready to build documentation from an existing OpenAPI file? Go to the Redoc quickstart and get started.
• Learn more about the project by visiting Redoc on GitHub.

2. Official Technical Reference & Guides (Redocly/website) Copy Chapter

File: README.md Copy Chapter

Redocly website

This repo is the source of the Redocly website (https://redocly.com).

Development Copy Chapter

Prerequisites Copy Section

• Node.js (version specified in .tool-versions)
• npm

Setup Copy Section

1. Install dependencies:

npm install

2. Start the development server:

npm start

Available Scripts Copy Section

• npm start - Start the development server using Redocly CLI preview
• npm run lint:markdown - Lint markdown files
• npm run lint:markdown:fix - Fix markdown linting issues
• npm run link-marketing-pages - Link a local build of @redocly/marketing-pages via yalc
• npm run unlink-marketing-pages - Remove the yalc link and restore the registry version

Project Structure Copy Chapter

.
├── docs/           # Documentation content
├── pages/          # Website pages
├── static/         # Static assets
├── images/         # Image assets
├── blog/           # Blog content
├── learn/          # Learning resources
└── @theme/         # Theme components

Remote content Copy Chapter

The /docs/cli, /docs/realm, and /docs/redoc content are sourced from other repositories using the remote content feature.

docs
├── cli
├── realm
├── redoc

Sidebars Copy Chapter

The sidebars are located in the root of the repo:

• docs-cli.sidebars.yaml
• docs-realm.sidebars.yaml
• etc...

Contributing Copy Chapter

Please ensure your contribution follows our style guidelines:

• Use Prettier for code formatting
• Follow the markdown linting rules defined in .markdownlint.yaml
• Follow the ESLint configuration

License Copy Chapter

This project is proprietary. See the LICENSE file for details.

File: docs/index.md Copy Chapter

seo: title: About Redocly documentation Copy Chapter

Redocly documentation

Welcome to the official Redocly Documentation.
Ready to build something amazing?

{% cards %}
{% card
title="Get started guide"
layout="horizontal"
align="start"
to="/docs/realm/get-started/index.md"
icon="./images/rocket-icon.svg"
iconVariant="filled"
%}
Go live with your docs in minutes using our guided setup
{% /card %}
{% /cards %}

Products Copy Chapter

{% cards columns=2 cardMinWidth=300 %}

{% card
title="Realm"
to="realm/index.md"
icon="./images/home-page/realm-logo.svg"
%}
The synthesis of Redocly's premier tools—Redoc, Revel, and Reef—united into a single, powerful platform.
{% /card %}

{% card
title="Workflows"
to="../docs-legacy/workflows/changelog.md"
icon="images/home-page/redocly-logo.svg"
%}
Legacy products
{% /card %}

{% card
title="VS Code extension"
to="vscode/index.md"
icon="images/home-page/vscode.svg"
%}
Extension that helps you write, validate, and maintain your OpenAPI documents
{% /card %}

{% /cards %}

Open source Copy Chapter

{% cards columns=2 cardMinWidth=300 %}

{% card
title="Redocly CLI"
to="cli"
icon="images/home-page/terminal-icon.svg"
%}
Open source OpenAPI multi-tool to manage, lint, validate and transform your OpenAPI files.
{% /card %}

{% card
title="Redoc Community Edition"
to="redoc"
icon="images/home-page/develop-docs-icon.svg"
%}
A clean and easy way to produce web-ready documentation from an OpenAPI description.
{% /card %}

{% card
title="Respect Community Edition"
to="respect/index.md"
icon="images/respect-icon.png"
%}
A tool to test API sequences described in Arazzo format.
{% /card %}

{% card
title="End user docs"
to="end-user/index.md"
icon="images/user-docs-icon.svg"

%}
Guide to the project's user interface.
{% /card %}

{% /cards %}

Learn Copy Chapter

{% cards columns=2 cardMinWidth=300 %}

{% card
title="Cafe API example"
to="https://github.com/Redocly/cafe-api"
icon="images/home-page/coffee.svg"
%}
Use our example to learn about OpenAPI or try out some new tools.
{% /card %}

{% card
title="Learn OpenAPI"
to="/learn/openapi/learning-openapi.md"
icon="images/home-page/extension-icon.svg"
%}
Resources for learning more about OpenAPI and how to use it.
{% /card %}

{% card
title="Learn Markdoc"
to="/learn/markdoc/index.md"
icon="images/home-page/markdoc-icon.svg"
%}
Next-generation markup resources and detailed tag library.
{% /card %}

{% card
title="API Guidelines builder"
to="../pages/api-governance/index.md"
icon="images/home-page/checklist-icon.svg"
%}
Use our interactive tool to build linting rules for your API.
{% /card %}

{% /cards %}