API Documentation

What is API documentation?

API documentation aims to provide technical information and instructions required for integrating other applications with the MentorED platform. The information included in the documentation will consist of requests and sample responses of each API as well as a postman collection of services. You can access the API documentation by visiting the URL associated with the respective services.

API Document Source file

The source content for API documentation, is maintained in a YAML file. The YAML file complies with OpenAPI version 3 specifications. Each request will have a unique response along with multiple scenarios such as response 200 or 400.

The Yaml file has 4 sections: info, servers, paths, and components (see the following table for more information)

Table 1: YAML File Contents

Yaml Section	What the Section Includes
Info	A title, version, description, and contact information

Postman Collection

Postman collection can be found inside src/api-doc, directly imported to the postman collection. It will also consist of env variables collection, which will be used across multiple API services.

How to generate API documentation files?

To generate API documentation files we need an API specification file in YAML format it should be in the api-doc folder. For generating API docs we have used the redoc library.

Command to generate API documentation

redoc-cli build -o ./api-doc/index.html ./api-doc/api-doc.yaml