Redocly: the right choice when looking for an API documentation tool

Great developer experience and helpful tech documentation are recently making the difference when Product & Tech teams want to deliver value for customers as quickly, frequently, and safely as possible.
In TUI Musement, we care about developer experience, and we try our best to provide clear, exhaustive, and consistent API documentation for an internal purpose. But it is particularly important for external purposes too, as we have around 70 partners who are integrating our APIs. For successful API integrations, third-parties developers need good API documentation at all stages: pre-integration stage, integration stage, and post-integration stage, where an up-to-date changelog provides the right support.

To always provide our partners with the best API documentation, and to keep consistency and alignment between internal teams, we decided to use Redocly, a new API documentation tool already used by our competitors such as Viator and GetYourGuide.
Our main goal was to have simultaneous management between the code release and the API documentation publish. In this way, our partners as well as internal teams can be always in line with the API lifecycle. Redocly suited all our needs as it can rely on a dedicated GIT repository where you can store and manage your API documentation. Specifically, Redocly can be used together with the GIT features and release new endpoints (or deprecate old ones), simultaneously publishing the fancy related API documentation. Moreover, you can gain easy and fast review flows between developers and tech writers, and you can handle multiple API versions.

Redocly provides you with a suite of services and features properly designed for the whole API lifecycle and allows you to transform a simple OpenAPI specification into a branded portal with an interactive and up to date API documentation.

After creating the Redocly account, you register your API by matching Redocly tool to the Source, namely, to your documentation-dedicated GIT repository.

Then, it’s time to add and set up the Reference section.

In this way you can automatically generate API documentation from your OpenAPI specification. You only need to select the Source and then you take care of the style. The UI is great, and partners can easily test endpoints while checking the documentation.

Finally, you add and set up the Portal section. The Portal section is directly matched to the Content folder of the GIT repo where you store and organize the documentation.

API docs can be fully customizable and branded. You get complete control of a navigation bar, sidebars and the footer.

You can style and create clear and easy to use content for the API documentation thanks to markdown features, diagrams with Mermaid.js, embeddable React_components, etc.

You can also integrate interactive API samples right into text descriptions. See this example from Viator.

Every time there is a change to the Reference section (i.e. a new endpoint has been released and imported to the OpenAPI specification), you can write down, style and add the related API documentation, simply create a Merge Request and easily publish the documentation.

Another great Redocly feature is the integration with Google Analytics and other providers: allowing insights into how your partners are using your API documentation.

Now our Redocly discovery goes on and new improvements to the TUI Musement API documentation are coming soon!

Useful links:

https://redoc.ly/
https://partner-api.musement.com/

Thanks to:

Erica Grandi
Casimiro Ciancimino
Lorenzo Fabiani
Simone Fumagalli