Introduction
How to use ReDoc for OpenAPI? In this blog post, I’m going to show you the practical way to use ReDoc for OpenAPI Documentation.
In recent times, Rest APIs are de-facto standards for client-server and service-to-service communication. As a business grows, the number of APIs also increases and, after some time it becomes very hard to manage API without using any comprehensive tool and standard. For this reason, the idea of OpenAPI came into the market and, which is a broadly adopted industry standard for describing modern APIs.
The process of defining API is very simple in OpenAPI that just required a single file in json or yaml format, but once the number of API increases then real problems starting to appear in the development and maintenance of this single file.
A clever person solves a problem. A wise person AVOIDS it. — Albert Einstein
ReDoc allows us to document API into multiple file definitions in standard structure and also provide CLI tool @redocly/openapi-cli that can use for validating definition, to generate docs and export OpenAPI definition.
Demo > How to do?
In this demo, we will see how to use OpenAPI and ReDoc together for documentation.
1. Installation
First of all, you must have nodejs installed on your machine. Then install create-openapi-repo globally:
npm install -g create-openapi-repo
2. Project Setup
Run the following command in your preferred folder to create OpenAPI multiple files and folder structure.
create-openapi-repo
Example: 
3. Defining APIs
For example, we have to create services for user management and product management then possible APIs are the following:
|_**User Service**_ | _**Product Service**_ |
|----------------------------------------------|----------------------------------------------------|
| - POST `/users` to create a new user | - POST `/products` to create a new product |
| - GET `/users` to get all users | - GET `/products` to get all products |
| - GET `/users/{username}` to get user | - GET `/products/{productId}` to get product |
| - PUT `/users/{username}` to edit user | - PUT `/products/{productId}` to edit product |
| - DELETE `/users/{username}` to delete user | - DELETE `/products/{productId}` to delete product |
API definitions using multiple files and folders structure with ReDoc:
openapi/
┣ code_samples/
┃ ┣ C#/
┃ ┃ ┗ echo/
┃ ┃ ┗ post.cs
┃ ┣ PHP/
┃ ┃ ┗ echo/
┃ ┃ ┗ post.php
┃ ┗ README.md
┣ components/
┃ ┣ headers/
┃ ┃ ┗ PageInfo.yaml
┃ ┣ schemas/
┃ ┃ ┣ Email.yaml
┃ ┃ ┣ Product.yaml
┃ ┃ ┗ User.yaml
┃ ┣ securitySchemes/
┃ ┃ ┣ api_key.yaml
┃ ┃ ┣ basic_auth.yaml
┃ ┃ ┗ main_auth.yaml
┃ ┗ README.md
┣ paths/
┃ ┣ products.yaml
┃ ┣ products@{productId}.yaml
┃ ┣ users.yaml
┃ ┗ users@{username}.yaml
┣ README.md
┗ openapi.yaml
In the main openapi yaml file we just need to link our separate definitions with API paths.
paths:
'/users':
$ref: 'paths/users.yaml'
'/users/{username}':
$ref: 'paths/users@{username}.yaml'
'/products':
$ref: 'paths/products.yaml'
'/products/{productId}':
$ref: 'paths/products@{productId}.yaml'
Why multiple files and folders?
If you don’t use multiple files and folders structure to manage definitions then you will end with the big file like dist.yaml. After looking at it, you might think it is not bad but this is a demo which has only 8 APIs which may not be in a real-world application. You might have 50 or 100 APIs then you will face the real problem of managing single file so that I recommend multiple files and folder structure to manage API definition.
- Easy to organize.
- Easy for development.
- Easy to re-use of objects to avoid duplication.
4. Lint, Build and Generate Docs
- To Lint
npm run test
- To Build
npm run build
- To Generate Docs
npm run start
5. Source Code > Github Link
Conclusion
In summary, managing a single OpenAPI definition file is a daunting task instead by using ReDoc we can organize API development in a better way, and also maintenance becomes very easy.