Repository files navigation

Generate beautiful API documentation from OpenAPI

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.

If you want to see how Redoc renders your OpenAPI definition,you can try it out online athttps://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 selectTRY IT.

• 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 thex-tagGroups specification extension
• Simple integration withcreate-react-app
• Code samples support (with vendor extension)
  

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

If you have Node installed, quickly generate documentation usingnpx:

npx @redocly/cli build-docs openapi.yaml

The tool outputs by default to a file namedredoc-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.

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

<redocspec-url="http://petstore.swagger.io/v2/swagger.json"></redoc><scriptsrc="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 ownspec-url to the<redoc> tag; this attribute can also be a local file. The JavaScript library can also be installed locally usingnpm and served from your own server, see theHTML deployment documentation for more details.

Check out thedeployment documentation for more options, and detailed documentation for each.

Redoc is Redocly's community-edition product. Looking for something more?We also offerhosted API reference documentationwith additional features including:

• Try-it console
• Automated code samples
• Pagination
• Extra theme options

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

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

Redoc is highly configurable, see theconfiguration documentation for details.

Redoc uses the followingspecification 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

The README for the1.x version is on thev1.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 examplev1.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.

seeCONTRIBUTING.md