Getting started with Redocly


For the past four years, we've been enhancing developer experience by making API reference docs from OpenAPI definitions. In the past two years, we further enhanced developer experience by making developer portals.

We've had the good fortune of working with a mix of well-respected technology companies, blue chips, and startups. We found one common thread. A good workflow yields a more productive team. A more productive team is a happier team.

Building a modern documentation workflow is a mind-boggling adventure.

Redocly is focused on servicing the API lifecycle. Our products are crafted to enable and enhance:

  • OpenAPI definition authoring, validation, and bundling
  • Docs-like-code
  • Single-sourcing
  • Previewing or sharing previews of changes
  • Automated deployments based on git ops
  • Dependency and usage tracking
  • Access controls on static generated content
React components
API registry
API docs
Code samples
Mock server
Guides and tutorials
Conceptual docs

The dashed boxes are planned for the future.


Writing valid OpenAPI definitions is an important starting block for API reference docs. Whether you design first or code first, valid OpenAPI definitions make a big difference in the quality of the documentation. We built a highly performant tool to lint (validate), and bundle your OpenAPI definitions. If you are writing your API definitions by hand, we recommend using our split command if you have an existing definition or our openapi-starter template repository to structure your repository.

Redocly has a VS Code plugin in active development. Get faster feedback when authoring.

All of our products can be managed using configuration files which you store in source control, further enhancing the docs-like-code experience.

Integrated to source control

We believe OpenAPI definitions should be stored in your source control software. We're integrated with GitHub, GitHub Enterprise, BitBucket cloud and server, Gitlab cloud and server, and Azure Repos. Each integration may work a little bit different. Throughout our docs, we'll use GitHub as our reference integration. Other integrations have specific pages explaining any differences.

You may also use other sources instead of source control, such as an API definition published at a URL or a file upload or CI/CD.

API registry

Our API registry validates and bundles your OpenAPI definitions and keeps track of them. It tracks usages and dependencies which helps automate modern cascading previews. For example, if a schema is used in three different doc projects, and a change is proposed in a pull request, Workflows will:

  1. Lint (validate) the OpenAPI definition.
  2. Bundle the OpenAPI definition as a snapshot.
  3. Build a preview for each project where it is used.

In the future, we will automate additional workflows, like building SDKs, mock servers, or more.

API docs

This is our flagship offer. Three-panel interactive API reference docs generated from your OpenAPI definitions.

Developer portals (beta)

Our developer portal starts from a template to make it easier to learn by example. Connect your OpenAPI definitions, and then craft your content in Markdown, and organize the navigation in yaml.

Our developer portals are deployed in production at Fortune 500 companies. It is running everywhere from our home base to outer space. It is stable. We consider it beta because it is feature incomplete. Want to help out? Join our team).