Redocly is an open source tool written in Typescript that
assists in managing your APIs effectively. What can it do?

We've recently covered the importance of documenting
your APIs in "Learn To Document Your API Correctly".
Towards that path to enlightenment, a condition that should be avoided at all costs is introducing breaking changes between your API versions as we discovered in "OpenAPI Diff Prevents API Breakages". To do that, our quest for better APIs has to be supported by good tooling.

So here's another great tool, Redocly CLI, that provides a holistic approach to API management. It empowers developers to comply to API design standards, produce excellent documentation, and expedite development cycles.

With it you can automate critical tasks for smooth deployment, generate publication-ready HTML documentation, bundle OpenAPI files and transform existing descriptions seamlessly.

In detail its features are :

• Produce beautiful API documentation, and automatically update it every time your OpenAPI description changes:redocly build-docs openapi.yaml
 
• Lint your OpenAPI description to check that it matches the expected OpenAPI standards:redocly lint openapi.yaml


• Break long OpenAPI files into smaller pieces so you can focus on what matters and let Redocly recombine the pieces into a single file for output:

redocly split pet. yaml --outDir=openapi

In the openapi directory, the split command "unbundles" the specified API description. Code samples, components, and paths are split from the root API description into separate files and folders.Then bundle with :
redocly bundle --output dist --ext json openapi/openapi. yaml openapi/pet.yaml

• Generate statistics about the structure of one or more API description files:redocly stats openapi/openapi.yaml

   

• Combine separate APIs into a single OpenAPI description:redocly join first-api.yaml second-api.json

The tool Supports OpenAPI 3. 1, 3. 0 and OpenAPI 2. 0 (legacy Swagger format).

Written in Typescript, it  can be installed as:

npx @redocly/cli lint path-to-root-file. yaml

or:

npm install @redocly/cli -g

It is also available as a Docker image for portability.

In conclusion, Redocly gives you some superior options. On the one hand you can design and experiment with your APIs locally and then push into production, while on the other, by incorporating it in your CI workflow you can check commits against standards and generate documentation.

More Information

Redocly

Related Articles

Learn To Document Your API Correctly

OpenAPI Diff Prevents API Breakages

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info