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.
Swagger-generated API Reference Documentation
<!DOCTYPE html>
<html>
<head>
<title>ReDoc</title>
<!-- needed for adaptive design -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<!--
ReDoc uses font options from the parent element
So override default browser styles
-->
<style>
body {
margin: 0;
padding: 0;
font-family: Verdana, Geneva, sans-serif;
font-size: 14px;
color: #333;
}
</style>
</head>
<body>
<redoc spec-url='http://petstore.swagger.io/v2/swagger.json'>
</redoc>
<script src="bower_components/redoc/dist/redoc.min.js"> </script>
</body>
</html>
Install using bower:
bower install redoc
or using npm:
npm install redoc --save
Alternatively you can just download redoc.min.js.
Then reference redoc.min.js in your HTML page:
<script src="bower_components/redoc/dist/redoc.min.js"> </script>
For npm:
<script src="node_modules/redoc/dist/redoc.min.js"> </script>
<redoc> element to your page<redoc spec-url="<url to your spec>"></redoc>
ReDoc makes use of the following vendor extensions:
x-logo - is used to specify API logox-traitTag - useful for handling out common things like Pagination, Rate-Limits, etcx-code-samples - specify operation code samplesspec-url - relative or absolute url to your spec filescroll-y-offset - If set, specifies a vertical scroll-offset. This is often useful when there are fixed positioned elements at the top of the page, such as navbars, headers etc.
scroll-y-offset can be specified in various ways:
Instead of adding spec-url attribute to the <redoc> element you can initialize ReDoc via globally exposed Redoc object:
Redoc.init(specUrl, options)
options is javascript object with camel-cased version of options names as the keys. For example:
Redoc.init('http://petstore.swagger.io/v2/swagger.json', {
scrollYOffset: 50
})
git clone https://github.com/Rebilly/ReDoc.gitcd ReDocnpm install
npm run jspm-installdemo/swagger.json with your own schemanpm starthttp://localhost:9000FAQs
ReDoc
The npm package redoc receives a total of 382,804 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
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.
Research
Security News
Malicious npm package postcss-optimizer delivers BeaverTail malware, targeting developer systems; similarities to past campaigns suggest a North Korean connection.