Formaloo API Documentations

This is a repository for Formaloo's API documentations. This repository contains the code, the meta data, and the descriptions needed to create the Formaloo API documentations. All you need to do is to run the docker-compose up command to run the scripts. The output is a directory that contains the html files needed to show the API documentations. All you need to do after running the container is to server the html files inside the html directory (which will be automatically created).

How does it work?

The scripts in this docker file will get the main API documentations from the different Formaloo services, load the with the extra descriptions for each endpoint, merge them all together and create an html file to server the documentation for each version of the API.

How do I Contribute?

The document for each endpoint contains tow main parts: Automated documentation and Manual descriptions.

1. Automated documentation: This part contains the endpoint address, all the request and response fields and their descriptions and settings, the method, the example codes, headers, etc. This is automatically generated by each service based on the code written in them.

2. Manual descriptions: This is any description needed to be written on each endpoint, what is it, how does it work, considerations, request/response examples, etc. This is the part you can contribute by adding any descriptions or examples you deem necessary or useful.

How do I write the manual description?

Each endpoint will load the manual description from a file in this repository, with the exact path and method of the endpoint. For example, for the update form endpoint on the version 2.0, has the following address: /v2.0/forms/{slug}/, and its documentation will be loaded from the following file: spec/docs/v2.0/forms/{slug}/patch.md and spec/docs/v2.0/forms/{slug}/put.md (since the update request supports both put and patch methods).

All documentation files should be written in Markdown format. The files for each endpoint can be manually added or will be automatically created after running the docker-compose up command. So if you want to write the documentation for a new endpoint and its documentation file is non-existing, you can either add the file manually or run the docker-compose up command so it's created automatically. (The second approach is recommended).

Contributing to the intro.md

Each version of the API contains an intro page (e.g. spec/docs/v2.0/intro.md). This file contains the introduction to the API, the current version, general considerations, and a guide on how to get started with the API.