Redoc is an open-source tool for generating interactive API documentation from OpenAPI (formerly Swagger) definitions. It provides a user-friendly interface for exploring and understanding API endpoints, parameters, and responses.
Render API Documentation
This feature allows you to render API documentation from an OpenAPI specification file. The `init` method takes the path to the OpenAPI file, optional configuration options, and the HTML element where the documentation should be rendered.
const Redoc = require('redoc');
Redoc.init('path/to/your/openapi.yaml', {
scrollYOffset: 50
}, document.getElementById('redoc-container'));Customization Options
Redoc allows for extensive customization of the rendered documentation. You can change the theme, colors, fonts, and other styles to match your branding.
const Redoc = require('redoc');
Redoc.init('path/to/your/openapi.yaml', {
theme: {
colors: {
primary: {
main: '#dd5522'
}
}
}
}, document.getElementById('redoc-container'));Standalone HTML Generation
Redoc provides a CLI tool to generate a standalone HTML file from an OpenAPI specification. This can be useful for hosting static API documentation without needing a server.
const { exec } = require('child_process');
exec('npx redoc-cli bundle path/to/your/openapi.yaml', (error, stdout, stderr) => {
if (error) {
console.error(`Error: ${error.message}`);
return;
}
if (stderr) {
console.error(`Stderr: ${stderr}`);
return;
}
console.log(`Stdout: ${stdout}`);
});Swagger UI is another popular tool for generating interactive API documentation from OpenAPI specifications. It offers a more traditional interface compared to Redoc and is highly customizable. Swagger UI is often used in conjunction with other Swagger tools for a complete API development workflow.
API Docs is a lightweight tool for generating API documentation from OpenAPI specifications. It focuses on simplicity and ease of use, making it a good choice for smaller projects or teams that need quick and straightforward documentation.
Spectacle is a tool for generating API documentation from OpenAPI specifications with a focus on readability and user experience. It offers a clean and modern interface, similar to Redoc, but with different customization options and features.
Redoc is an open source tool for generating documentation from OpenAPI (formerly Swagger) definitions.
By default Redoc offers a three-panel, responsive layout:
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.
x-tagGroups specification extensioncreate-react-app
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 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.
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.
Check out the deployment documentation for more options, and detailed documentation for each.
Redoc is Redocly's community-edition product. Looking for something more? We also offer hosted API reference documentation with additional features including:
docs/ folder)A sample of the organizations using Redocly tools in the wild:
Pull requests to add your own API page to the list are welcome
Redoc is highly configurable, see the configuration documentation for details.
Redoc uses the following specification extensions:
x-logo - is used to specify API logox-traitTag - useful for tags that refer to non-navigation properties like Pagination, Rate-Limits, etcx-codeSamples - specify operation code samplesx-badges - specify operation badgesx-examples - specify JSON example for requestsx-nullable - mark schema param as a nullablex-displayName - specify human-friendly names for the menu categoriesx-tagGroups - group tags by categories in the side menux-servers - ability to specify different servers for API (backported from OpenAPI 3.0)x-ignoredHeaderParameters - ability to specify header parameter names to ignorex-additionalPropertiesName - ability to supply a descriptive name for the additional property keysx-summary - for Response object, use as the response button text, with description rendered under the buttonx-extendedDiscriminator - in Schemas, uses this to solve name-clash issues with the standard discriminatorx-explicitMappingOnly - in Schemas, display a more descriptive property name in objects with additionalProperties when viewing the property list with an objectThe 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:
v2.0.0: https://cdn.redoc.ly/redoc/v2.0.0/bundles/redoc.standalone.jslatest release: https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.jsAdditionally, all the 1.x releases are hosted on our GitHub Pages-based CDN (deprecated):
v1.2.0: https://rebilly.github.io/ReDoc/releases/v1.2.0/redoc.min.jsv1.x.x release: https://rebilly.github.io/ReDoc/releases/v1.x.x/redoc.min.jslatest 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.see CONTRIBUTING.md
FAQs
ReDoc
The npm package redoc receives a total of 508,637 weekly downloads. As such, redoc popularity was classified as popular.
We found that redoc demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.