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
Servers	Information on the development server and local server URLs
Paths	List of API endpoints, a description of API specifications, and different parameters required to make an API call. Also includes a request body and responses which will refer to different components in the components section.
Components	All request bodies and response result structures for each API.

For more information on API documentation, see: https://redocly.com/docs/

Changes in API documentation

If APIs are updated or new APIs are added to services, you must update api the API documentation.

To update API documentation, you need to

Update YAML files in associated with each service (see the Table 2 for more details).
Update the Postman collection available in the src/api-doc folder of each service.

Service	YAML file
Users	https://github.com/ELEVATE-Project/user/blob/master/src/api-doc/api-doc.yam
Mentoring	https://github.com/ELEVATE-Project/mentoring/blob/master/src/api-doc/api-doc.yaml
Notification	https://github.com/ELEVATE-Project/notification/blob/master/src/api-doc/api-doc.yaml

After the changes are done, you can raise a Pull Request (PR).

Postman Collection

Postman collection is located in the folder: src/api-doc folder. directly imported to the pPostman 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 in the api-doc folder. MentorED API documents can be generated using the redoc library.

Command to generate API documentation

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