---
title: "Documenting your API with OpenAPI (Swagger) and Redoc | WebhookRelay"
meta:
  "og:description": "API tooling review and a guide on how to document your API with Swagger's OpenAPI and Redoc"
  "og:title": "Documenting your API with OpenAPI (Swagger) and Redoc"
  description: "API tooling review and a guide on how to document your API with Swagger's OpenAPI and Redoc"
---

![Stripes](https://webhookrelay.com/blog/openapi-redoc-tutorial/images/stripes.svg)

# **Documenting your API with OpenAPI (Swagger) and Redoc**

API tooling review and a guide on how to document your API with Swagger's OpenAPI and Redoc

## [What is Redoc?](#what-is-redoc)

Redoc is an open-source tool that generates beautiful, responsive API documentation from OpenAPI (Swagger) specifications. It provides a three-panel layout with a navigation menu, detailed descriptions, and interactive code samples, making it easy to create professional API documentation that can be embedded in any website.

In this article, we will review several popular editors suitable for documenting APIs with the OpenAPI 3.0 specification, different themes that can render the spec, as well as hosting strategies.

## [TL;DR](#tldr)

Best combination that we found:

- Use [OpenAPI 3.0](https://www.openapis.org/)
- Implement specification with [VSCode Swagger Extension](https://github.com/arjun-g/vs-swagger-viewer)
- Use GitHub pages with [Redoc](https://github.com/Rebilly/ReDoc) for a good looking & free hosting

## [Choosing API specification format](#choosing-api-specification-format)

I guess it’s safe to say that OpenAPI is now the most popular API specification out there. You can find out more about it here: [https://www.openapis.org/](https://www.openapis.org/). Other contenders:

- RAML
- API Blueprint
- WADL
- Slate

You can read more about other top specification formats on an excellent Nordic APIs article here: [https://nordicapis.com/top-specification-formats-for-rest-apis/](https://nordicapis.com/top-specification-formats-for-rest-apis/)

## [OpenAPI vs/and Swagger](#openapi-vsand-swagger)

Short history: OpenAPI 3.0 was the first official release since it was donated to the OpenAPI initiate by the [SmartBear Software](https://smartbear.com/) (and renamed from the Swagger Specification). A lot of people still think (myself included before I did some research) that Swagger is still a specification, however, currently:

- OpenAPI is a specification
- Swagger provides tools for writing specification, generating code & hosting it.

In the past years, OpenAPI has been embraced by major enterprises and startups of various sizes.

## [Editors](#editors)

Once you have a specification chosen, it’s important to look for a good way to actually write it down. I initially started with [https://apiary.io](https://apiary.io) as they offer an editor with Swagger 2.0 and API Blueprint options (defaults to API Blueprint so watch out:) as well as hosting your documentation on their service:

![Apiary editor](https://webhookrelay.com/blog/openapi-redoc-tutorial/images/blog/openapi-redoc-guide/apiary-editor.png)

Sounds like a good deal? It probably is, since it offers an all-in-one package - editor, syntax check and even hosts your docs for free. Let's have a look at other options :)

### [Swagger editor](#swagger-editor)

I then looked into Swagger editor ([https://editor.swagger.io/](https://editor.swagger.io/)) but I opted for a self-hosted via Docker:

![Swagger editor](https://webhookrelay.com/blog/openapi-redoc-tutorial/images/blog/openapi-redoc-guide/swagger-editor.png)

It’s very similar to apiary.io offering but the main problem I found with both of them was that they are just not as fast as my editor that I use locally.

### [Swagger VSCode extension](#swagger-vscode-extension)

Naturally, I checked out VSCode extensions marketplace and found this excellent piece [https://github.com/arjun-g/vs-swagger-viewer](https://github.com/arjun-g/vs-swagger-viewer):

![Swagger editor VSCode](https://webhookrelay.com/blog/openapi-redoc-tutorial/images/blog/openapi-redoc-guide/swagger-vscode.png)

With the extension you get:

- autocompletion
- all your shortcuts work
- integrated Git

All in all, while I started documenting API in Apiary, by switching to VSCode extension it greatly improved the speed at which I could document.

## [Hosting your documentation](#hosting-your-documentation)

While I really enjoy both Swagger 2.0 and OpenAPI specification format, swagger docs weren’t particularly visually attractive to me. Apiary does offer a nice theme:

![Apiary docs](https://webhookrelay.com/blog/openapi-redoc-tutorial/images/blog/openapi-redoc-guide/apiary-docs.png)

And would probably be my first choice of hosting if we didn't already have a website where we host docs. But at the end of the day, it’s just a single page and having a 3rd party hosting dependency was a bit too much.

## [Enter ReDoc](#enter-redoc)

After spending a bit of time looking at various themes and tools, I found my favorite - ReDoc ([https://github.com/Rebilly/ReDoc](https://github.com/Rebilly/ReDoc).) It offers an incredibly nice theme, the project is active and very customizable. The main reason I chose ReDoc was because of how easy it is to embed documentation with it.

## [How to Set Up Redoc Documentation](#how-to-set-up-redoc-documentation)

Follow these steps to set up Redoc for your API documentation:

1. **Create Your OpenAPI Specification** - Write your API documentation in OpenAPI 3.0 or Swagger 2.0 format using a YAML or JSON file
2. **Host Your Specification File** - Put your openapi.yaml or swagger.yaml in a publicly accessible place (GitHub repo, CDN, or your own server)
3. **Add Redoc Script** - Include the Redoc standalone JavaScript bundle in your HTML page
4. **Initialize Redoc** - Call Redoc.init() with your specification URL and optional configuration
5. **Customize Appearance** - Configure options like scroll offset, theme colors, and button visibility
6. **Deploy Your Documentation** - Host your documentation page on GitHub Pages, Netlify, or your own web server

### [Example Implementation](#example-implementation)

Here's how to embed Redoc in your website:

1. Put your openapi.yaml or swagger.yaml in a publicly accessible place. In our case I have put it in a Git repo: [https://github.com/webhookrelay/swagger-webhookrelay/blob/master/openapi.yaml](https://github.com/webhookrelay/swagger-webhookrelay/blob/master/openapi.yaml) Storing it in a git repo offers a nice feature - you edit, push it and it always stays up-to-date without redeploying your website.
2. In your website add these lines:

```
<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
<script>
   Redoc.init('https://raw.githubusercontent.com/webhookrelay/swagger-webhookrelay/master/openapi.yaml', {
       scrollYOffset: 60,
       hideDownloadButton: true
   }, document.getElementById('redoc'))
</script>
```

And that's it, your API reference is now hosted:

![Redoc Webhook Relay API reference](https://webhookrelay.com/blog/openapi-redoc-tutorial/images/blog/openapi-redoc-guide/redoc-whr.png)

## [API Documentation Tools Comparison](#api-documentation-tools-comparison)

Here's how Redoc compares to other popular API documentation tools:

| Feature | Redoc | Swagger UI | Apiary | Slate |
| --- | --- | --- | --- | --- |
| **OpenAPI Support** | ✓ 3.0 & 2.0 | ✓ 3.0 & 2.0 | ✓ 2.0 only | ✗ Markdown |
| **Visual Design** | Modern 3-panel | Classic 2-panel | Modern | Developer-focused |
| **Customization** | High | Medium | Low | High |
| **Hosting** | Self-hosted/CDN | Self-hosted/CDN | Cloud-hosted | Self-hosted |
| **Interactive Examples** | ✓ Yes | ✓ Try it out | ✓ Console | ✓ Yes |
| **Open Source** | ✓ Yes | ✓ Yes | ✗ No | ✓ Yes |
| **Ease of Setup** | Very Easy | Easy | Very Easy | Moderate |
| **Cost** | Free | Free | Paid plans | Free |

Redoc stands out for its beautiful design, ease of embedding, and excellent OpenAPI 3.0 support. It's ideal if you want professional-looking documentation without complex setup.

## [Conclusion](#conclusion)

Documenting your API can be quite fun if you pick the right tools that are not slowing you down. In our case we used a nice editor with features tailored to OpenAPI spec and publishing your API docs to the world can also be a pain-free experience.

Obviously, suggested tools were only the best for me, I suggest that before you start documenting your own APIs you would also do a 30-minute research with some trials on different editors, themes and hosting. Maybe you will find some other combination that suits you better. At the end of the day, choosing the right tooling will save you a lot of time :) good luck! Worst case scenario - once the specification is done, it's easy to try out different themes and hosting options as well.

> Bonus: Swagger 2.0 to OpenAPI 3.0 converter: [https://openapi-converter.herokuapp.com/](https://openapi-converter.herokuapp.com/)

### [Reference](#reference)

- [https://trends.google.com/trends/explore?cat=13&q=swagger,openapi,raml](https://trends.google.com/trends/explore?cat=13&amp;q=swagger,openapi,raml)
- [https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/](https://swagger.io/blog/api-strategy/difference-between-swagger-and-openapi/)
- [https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#oasDocument)
- [https://nordicapis.com/top-specification-formats-for-rest-apis/](https://nordicapis.com/top-specification-formats-for-rest-apis/)
- [https://raml.org/](https://raml.org/)
- [https://github.com/Rebilly/ReDoc](https://github.com/Rebilly/ReDoc)