Designing Restful APIs using an API-First Approach — Documentation
By: Nicolas Takashi
Tags: Api Development, Redoc, Documentation, Rest Api, Open Api

In the last months, I have been writing about how to develop better APIs using an API-First strategy using OpenAPI. We could see how powerful is OpenAPI and its ecosystem.

To keep the standard and show you how the OpenAPI can improve developer’s productivity and promote a better experience for those that consume your API, I will talk about API Documentation.

Photo by Kerttu on Pixabay

The most important thing that an API Developer must bear in mind is to provide a better developer experience as possible and to achieve this challenge. We might use a bunch of great tools and practices.

📕 API Documentation — A guide for your API

API Documentation is an essential practice to promote a good developer experience, but, unfortunately, most of the APIs do not take advantage of this practice to deliver better APIs.

A good API Documentation begins with a good API Design, so after that, clear descriptions improve the client’s understanding when the API provider needs to explain something else that is not clear in the API Design. Other practices such, Code Samples and API Console will be the cake icing for the developer experience.

📝 ReDoc — Documentation For The Win

ReDoc is an open-source project with more than 11 thousand stars in its Github Repository that believes that documentation the API Foundation. It is a powerful tool that provides a documentation portal for the API, using OpenAPI (formerly known as Swagger) as the source of truth.

Creating API Documentation

In the official documentation, there is a couple of options to build a ReDoc project. Today I will show you how to set up a ReDoc project using React Create App.

Bear in mind that I’m using the same Git Repository that I shared with you at the beginning of the series.

Getting Start

First things first, let’s run the command below to create a new react project.

npx create-react-app docs

Now we need to add ReDoc and its dependencies.

yarn add redoc mobx styled-components core-js

Now, we can configure the ReDoc and see the API documentation output. To configure it, you need to edit the App.js file to looks like the example below.

ReDoc — React Setup

Believe you or not, we finished the ReDoc basic configuration. There are more options available to be configured, such as themes, schema titles, scroll, and so on.

Not let’s add bundle the OpenAPI documents as JSON to the docs folder, enabling the ReDoc to render it. To do that, you need to run the command below.

swagger-cli bundle specs/api.yaml -o ./docs/src/api.json -t json

🧑‍💻 Keep your eyes open

After all, we will see how the ReDoc looks like and what we can do to improve the API Documentation created by ReDoc using the OpenAPI as the source of the truth.

But to not to lose the habit, run another command to start the documentation project.

yarn start

Now you can enjoy how it looks.

ReDoc — API Documentation

As you can see above, it looks great, and it was simple to configure everything needed.

Brading your documentation

To make it even excited, you can add an API Logo, adding the content below to the OpenAPI in the info section.

After that, restart the application to see the output below.

ReDoc — Brand Documentation

Given a gift for the API consumers

Combining API Design with API Documentation, the developers have almost everything needed to consume the API.

If you wish to improve even more the developer experience during the API consumption, you can provide code samples.

To our delight, redoc elegantly supports this, adding an extension named x-codeSamples with the list of samples that you want to provide.

Code samples support the most popular languages, and you can check the available list by clicking here.

The code sample structure looks like the example below.

lang: JavaScript

source: console.log('Hello World');

In this article, I will use the samples in a separate file to improve the readability, considering that code samples can be extensive. The code samples will be under the following directory structure.

.

├── js

│ ├── tasks

│ │ ├── get.yaml

│ │ └── post.yaml

│ └── tasks-by-id

│ ├── delete.yaml

│ ├── get.yaml

│ └── put.yaml

└── shell

├── tasks

│ ├── get.yaml

│ └── post.yaml

└── tasks-by-id

├── delete.yaml

├── get.yaml

└── put.yaml

Now I can add the code samples extension to the OpenAPI path section and restart the application to see the result below.

ReDoc — Code Samples

Now it is easier to interact with the API, and we can create how many samples you want to provide to the API consumers.

🏁 Conclusion

As we can see, ReDoc provides a great API documentation portal with low effort using as the source of truth, OpenAPI documents previously created in the API Design session.

ReDoc keeps evolving, and there is an API Console feature in the project backlog, and to me, this feature will take the project to the next level.

As usual, all the code is available in the Github Repository. Let me know what do you think about this strategy? Do you already know it?

Comment below, and let’s share the experiences.

I hope you enjoy it and see you soon.