A quick guide to creating API docs with Redocly

Creating API Docs using Open API Specs

Introduction

This is a very simplistic guide on using Redocly’s free open source API documentation library.

The key requirements for me personally was an API that wasn’t going to break the bank (a lot of auto generated ones out there charge nearly 100 dollars a month!) and something that follows the OpenApi 3.0 specification.

Create OpenApi Spec files. (yaml or json files)

The first step is to create all your endpoints by following the openAPI specification. I won’t go into depth but there are some good examples out there of they look like.

Setting up Redocly API

yarn install @redocly/cli

Then create a redocly.yaml file in root directory.

extends:
  - recommended

apis:
  this_is_my_api:
    root: ./path_to_your_spec/api.yaml
    rules:
      no-ambiguous-paths: error

theme:
  openapi:
    generateCodeSamples:
      languages:
        - lang: curl
        - lang: Python
        - lang: JavaScript
    theme:
			# https://redocly.com/docs/api-reference-docs/configuration/theming/

With that set up. You can quickly view your api docs by running

redocly preview-docs this_is_my_api

Then you can build a html file out of it using

redocly build this_is_my_api

That is the main gist of it all! In the future I will add more on the topic of adding themes and html templates. But in the meantime, if you want a quick API doc, Redocly is a really cool and quick way to do it.