DOCSEARCHbyAlgolia
Submit Docs

ReDoc

repository·main·Indexed 12 days ago

https://github.com/redocly/redoc

An open-source tool for generating responsive, three-panel API documentation from OpenAPI 3.1, 3.0, and Swagger 2.0 definitions. Version 2.5.3 supports deployment via Docker, a standalone JavaScript bundle, or the Redocly CLI. It features extensive customization through a theme object, functional settings, and vendor extensions such as x-logo, x-tagGroups, and x-codeSamples.

Tokens
10.7K
Snippets
46
Records
62
Agent score
95%

What's inside ReDoc

  1. Choose a Redoc deployment method

    main

    Redoc provides several ways to render your OpenAPI definition depending on your environment and application architecture:

    • Live demo: A quick way to preview how your OpenAPI renders by entering your definition's URL in the Redoc live demo.
    • HTML element: Best for typical website deployments where you want to embed Redoc into an existing page.
    • React component: Designed for users building React-based applications.
    • Docker image: Ideal for container-based or cloud-native deployments.
    • Redocly CLI: A command-line interface option for users who prefer terminal-based workflows.

  2. Use x-traitTag to create non-hierarchical tags

    main

    By default, tags in Redoc act as groups that contain operations. If you set x-traitTag: true on a Tag object, it is treated as a 'trait' rather than a group.

    Trait tags are listed in the side menu but do not have sub-items (operations). They are useful for displaying common cross-cutting concerns like Pagination or Rate-Limits along with their descriptions.

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

  3. Understand default Security Definitions injection behavior

    main

    If you do not provide an explicit injection tag (<!-- Redoc-Inject: <security-definitions> -->) in your specification's description, Redoc follows these default rules:

    1. Automatic Append: Redoc will append the Security Definitions widget to the end of the description field under an Authentication header.
    2. Collision Prevention: If an Authentication header is already present in your description, Redoc will not insert or render the Security Definitions widget to avoid duplication.

  4. Self-host Redoc dependencies

    main

    While using the CDN is the simplest method, you can self-host Redoc by installing it via npm and referencing the local bundle path. This is recommended for closed environments or when you need to manage external dependencies manually.

    # Install via npm
npm install redoc

# Reference in HTML
<script src="node_modules/redoc/bundles/redoc.standalone.js"> </script>

  5. Inject Security Definitions into an OpenAPI description

    main

    You can manually control where the Security Definitions widget appears in your documentation by placing a specific HTML comment within your OpenAPI specification's description field. This allows you to place the authorization information under a custom header or specific section.

    The injection instruction is wrapped in an HTML comment, ensuring it is visible only in Redoc and remains hidden in other tools like SwaggerUI.

    Use the following syntax:

    <!-- Redoc-Inject: <security-definitions> -->
    ## Authorization

Some description

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

...

  6. Use the RedocStandalone React component

    main

    The RedocStandalone component is the primary way to embed Redoc into a React application. You can provide your OpenAPI specification either via a remote URL (specUrl) or as a local JavaScript object (spec).

    import { RedocStandalone } from 'redoc';

// Option 1: Using a URL
<RedocStandalone specUrl="url/to/your/spec"/>

// Option 2: Using an object
<RedocStandalone spec={/* spec as an object */}/>

  7. Deploy ReDoc on OpenShift

    main

    The ReDoc image is designed to comply with OpenShift Container Platform-Specific Guidelines, specifically supporting Arbitrary User IDs.

    To allow the container to run with non-root user IDs, the image has been configured so that directories modified at startup or by the Nginx process (such as /etc/nginx, /usr/share/nginx/html, /var/cache/nginx, /var/log/nginx, and /var/run) are owned by the root group and are read/writable by that group.

    Important Note on Ports: Since OpenShift restricts the default port 80, you must use the PORT environment variable to specify an alternative port (e.g., 8080) and configure your container spec to match.

  8. Inject Security Definitions into the description

    main
    You can customize where the Security Definitions widget appears by injecting it into a specific location within your OpenAPI specification's description field. Refer to the security definitions injection guide for implementation details.

  10. Embed Redoc in an HTML page

    main

    To render Redoc directly in an existing or new HTML page, add the <redoc> custom element to the <body> and include the Redoc standalone JavaScript bundle via a <script> tag. Use the spec-url attribute on the <redoc> tag to point to your OpenAPI definition (can be a URL or a local file path).

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

  11. Generate documentation from the CLI

    main

    You can quickly generate standalone HTML documentation from an OpenAPI or Swagger specification using the Redocly CLI via npx. By default, the tool outputs a file named redoc-static.html.

    npx @redocly/cli build-docs openapi.yaml