Redoc

https://redocly.com/docs/redoc
Admin
Redoc is an open-source API documentation tool that generates web-ready documentation from OpenAPI...
Tokens:10,517
Snippets:110
Trust Score:10
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and run Node.js http-server

Source: https://redocly.com/docs/redoc/deployment/intro

Commands to install and start the http-server utility using Node.js.

```bash
npx http-server
```

```bash
http-server
```

--------------------------------

### x-tagGroups YAML example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Example of defining tag groups in YAML format.

```yaml
x-tagGroups:
  - name: User Management
    tags:
      - Users
      - API keys
      - Admin
  - name: Statistics
    tags:
      - Main Stats
      - Secondary Stats
```

--------------------------------

### x-enumDescriptions example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Provides a schema with enum values and corresponding x-enumDescriptions to supply human-readable context for each option.

```yaml
components:
  schemas:
    TicketType:
      description: Type of ticket being purchased.
      Use `general` for regular museum entry and `event` for tickets to special events.
      type: string
      enum:
        - event
        - general
      x-enumDescriptions:
        event: Event Tickets _(timed entry)_
        general: General Admission
      example: event
```

--------------------------------

### Run Redoc CE container

Source: https://redocly.com/docs/redoc/deployment/docker

Start the container and map port 8080 on the host to port 80 in the container.

```bash
docker run -p 8080:80 redocly/redoc
```

--------------------------------

### x-logo YAML example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Example of the x-logo extension defined within the info object using YAML format.

```yaml
info:
  version: "1.0.0"
  title: "Swagger Petstore"
  x-logo:
    url: "https://redocly.github.io/redoc/petstore-logo.png"
    backgroundColor: "#FFFFFF"
    altText: "Petstore logo"
```

--------------------------------

### Initialize Redoc CE with JavaScript

Source: https://redocly.com/docs/redoc/deployment/html

An example of initializing Redoc CE inside a specific <div> container using the Redoc.init method and custom configuration.

```html
<!DOCTYPE html>
<html>
  <head />
  <body>
    <H1>Redoc CE in action</H1>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
    <div id="redoc-container"></div>

    <script>
      Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
        "expandResponses": "200,400"
      }, document.getElementById('redoc-container'))
    </script>
  </body>
</html>
```

--------------------------------

### x-logo JSON example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Example of the x-logo extension defined within the info object using JSON format.

```json
{
  "info": {
    "version": "1.0.0",
    "title": "Swagger Petstore",
    "x-logo": {
      "url": "https://redocly.github.io/redoc/petstore-logo.png",
      "backgroundColor": "#FFFFFF",
      "altText": "Petstore logo"
    }
  }
}
```

--------------------------------

### Install Redoc CE dependencies

Source: https://redocly.com/docs/redoc/deployment/react

Install the necessary peer dependencies for Redoc CE using npm.

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

--------------------------------

### x-traitTag example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Example of defining a tag as a trait tag to display it in the side-menu without subitems.

```json
{
    "name": "Pagination",
    "description": "Pagination description (can use markdown syntax)",
    "x-traitTag": true
}
```

```yaml
name: Pagination
description: Pagination description (can use markdown syntax)
x-traitTag: true
```

--------------------------------

### x-tagGroups JSON example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Example of defining tag groups in JSON format. Ensure all tags are included in a group, otherwise they will not be displayed.

```json
{
  "x-tagGroups": [
    {
      "name": "User Management",
      "tags": ["Users", "API keys", "Admin"]
    },
    {
      "name": "Statistics",
      "tags": ["Main Stats", "Secondary Stats"]
    }
  ]
}
```

--------------------------------

### Run Redoc CE with custom SPEC_URL

Source: https://redocly.com/docs/redoc/deployment/docker

Start the container while specifying a custom OpenAPI description URL using the SPEC_URL environment variable.

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

--------------------------------

### Run Python 2 HTTP server

Source: https://redocly.com/docs/redoc/deployment/intro

Command to start a local HTTP server using Python 2 in the project directory.

```python
python -m SimpleHTTPServer 8000
```

--------------------------------

### Run Python 3 HTTP server

Source: https://redocly.com/docs/redoc/deployment/intro

Command to start a local HTTP server using Python 3 in the project directory.

```python
python3 -m http.server
```

--------------------------------

### Code Sample Object example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Example of a Code Sample Object used within x-codeSamples to provide operation code snippets.

```json
{
  "lang": "JavaScript",
  "source": "console.log('Hello World');"
}
```

```yaml
lang: JavaScript
source: console.log('Hello World');
```

--------------------------------

### x-additionalPropertiesName example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Demonstrates using x-additionalPropertiesName to provide a descriptive name for additional properties keys in a schema.

```yaml
Player:
  required:
  - name

  properties:
    name:
      type: string

  additionalProperties:
    x-additionalPropertiesName: attribute-name
    type: string
```

--------------------------------

### x-explicitMappingOnly example

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

Shows how to use x-explicitMappingOnly within a discriminator to limit the selectpicker to explicitly defined mappings.

```yaml
Pet:
  type: object
  required:
    - name
    - photoUrls
  discriminator:
    propertyName: petType
    x-explicitMappingOnly: true
    mapping:
      cat: "#/components/schemas/Cat"
      bee: "#/components/schemas/HoneyBee"
```

--------------------------------

### Configure Redoc CE Properties

Source: https://redocly.com/docs/redoc/deployment/html

Add configuration properties directly to the <redoc> HTML tag. This example displays required properties at the top of the list.

```html
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json' required-props-first=true></redoc>
```

--------------------------------

### Build documentation with CLI configuration

Source: https://redocly.com/docs/redoc

Run the build-docs command to generate documentation using the detected redocly.yaml configuration file.

```sh
redocly build-docs openapi.yaml
```

--------------------------------

### Build API documentation with build-docs

Source: https://redocly.com/docs/redoc/deployment/cli

Use this command to transform an API description file into a human-readable HTML file. Replace apis/openapi.yaml with the path to your specific API description file.

```bash
npx @redocly/cli build-docs apis/openapi.yaml
```

--------------------------------

### Generate documentation with Redocly CLI

Source: https://redocly.com/docs/redoc

Use the npx command to generate static HTML documentation from an OpenAPI specification file.

```sh
npx @redocly/cli build-docs openapi.yaml
```

--------------------------------

### Configure Redoc CE with redocly.yaml

Source: https://redocly.com/docs/redoc

Define visual theme settings and OpenAPI behavior in a redocly.yaml configuration file.

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

--------------------------------

### Configure RedocStandalone options

Source: https://redocly.com/docs/redoc/deployment/react

Pass an options object to customize the rendering, such as enabling native scrollbars or changing theme colors.

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

--------------------------------

### Import RedocStandalone component

Source: https://redocly.com/docs/redoc/deployment/react

Import the RedocStandalone component from the redoc package.

```js
import { RedocStandalone } from 'redoc';
```

--------------------------------

### Redoc.init Function Signature

Source: https://redocly.com/docs/redoc/deployment/html

The signature for the Redoc.init function used to initialize Redoc CE via JavaScript.

```javascript
Redoc.init(specOrSpecUrl, options, element, callback)
```

--------------------------------

### Basic Redoc CE HTML Template

Source: https://redocly.com/docs/redoc/deployment/html

A standard HTML template for embedding Redoc CE. Replace the spec-url attribute with your OpenAPI file path or URL.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Redoc CE</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    Redoc CE doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'></redoc>
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
  </body>
</html>
```

--------------------------------

### Reference Redoc CE via CDN

Source: https://redocly.com/docs/redoc/deployment/html

Include the Redoc CE script in your HTML file using a CDN URL.

```html
<script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"> </script>
```

--------------------------------

### Render OpenAPI description with Redoc CE HTML

Source: https://redocly.com/docs/redoc/quickstart

Use this HTML template to render an OpenAPI description. Replace the spec-url attribute in the <redoc> element with the URL or local file path to your OpenAPI specification.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Redoc CE</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link
      href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
      rel="stylesheet"
    />

    <!--
    Redoc CE doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <!--
    Redoc CE element with link to your OpenAPI description
    -->
    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <!--
    Link to Redoc CE JavaScript on CDN for rendering standalone element
    -->
    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
  </body>
</html>
```

--------------------------------

### DownloadUrlItem object structure

Source: https://redocly.com/docs/redoc/config

Defines the structure for the downloadUrls option, which specifies URLs for downloading OpenAPI descriptions or related files.

```javascript
{
  title?: string,
  url: string
}
```

--------------------------------

### Redoc Theme Configuration Settings

Source: https://redocly.com/docs/redoc/config

A comprehensive YAML configuration structure for customizing Redoc CE 2.x themes. Settings include spacing, breakpoints, typography, and layout-specific styling for sidebars and panels.

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

--------------------------------

### Pull Redoc CE Docker image

Source: https://redocly.com/docs/redoc/deployment/docker

Download the latest Redoc CE image from Docker Hub.

```bash
docker pull redocly/redoc
```

--------------------------------

### Render RedocStandalone with specUrl

Source: https://redocly.com/docs/redoc/deployment/react

Use the RedocStandalone component by providing a URL to your OpenAPI definition.

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

--------------------------------

### Inject Security Definitions widget

Source: https://redocly.com/docs/redoc/security-definitions-injection

Use the <!-- Redoc-Inject: <security-definitions> --> HTML comment to place the widget within your info.description. This tag is hidden in other tools like SwaggerUI.

```markdown
...
## Authorization

Some description

<!-- Redoc-Inject: <security-definitions> -->
...
```

--------------------------------

### Configure Redoc CE Theme

Source: https://redocly.com/docs/redoc/deployment/html

Pass a JSON string to the theme attribute to customize the appearance, such as changing the sidebar background color.

```html
    <redoc spec-url='http://petstore.swagger.io/v2/swagger.json'
       required-props-first=true
       theme='{
         "sidebar": {
           "backgroundColor": "lightblue"
         }
       }'
    ></redoc>
```

--------------------------------

### Specify onLoaded callback

Source: https://redocly.com/docs/redoc/deployment/react

Use the onLoaded callback to execute logic after Redoc CE is rendered or if an error occurs.

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

--------------------------------

### Embed Redoc CE via HTML tag

Source: https://redocly.com/docs/redoc

Add the redoc element and the standalone JavaScript bundle to an HTML page to render API documentation.

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

--------------------------------

### Render RedocStandalone with spec object

Source: https://redocly.com/docs/redoc/deployment/react

Use the RedocStandalone component by passing your OpenAPI definition as an object.

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

--------------------------------

### AI Agent Feedback Payload

Source: https://redocly.com/docs/redoc/redoc-vendor-extensions

A JSON payload structure for AI agents to report missing information, outdated endpoints, or execution errors in the documentation.

```json
{
  "agent": "e.g. Cursor, Claude Code",
  "url": "https://redocly.com/docs/redoc/redoc-vendor-extensions",
  "targetFeature": "The specific API or feature being used",
  "summary": "One-sentence summary of the documentation flaw",
  "details": "Expected vs actual behavior; missing steps; errors"
}
```
Tokens:
Raw