Generating API documentation

The LiteFarm api service uses expressOasGenerator (EOG) to automatically create API documentation.

EOG generates endpoint documentation by statically analyzing route definition code.

It generates documentation of request and response details by monitoring network traffic.

The version-controlled files oas.json and oas_v3.json contain “official” documentation. To update them, define the environment variable UPDATE_OAS_FILES (any value), run automated tests, and commit the modified files..

EOG serves the documentation from the api service at public URL /api-docs. When running in production mode, the documentation served is only the contents of the JSON files. In other modes, EOG incorporates changes and additions it detects, but does not save them to the JSON files unless the env var is set.

To observe all network payloads, EOG's middlewares must be first and last in the chain, and (contrary to typical practices) the chain cannot be broken. IOW, some payloads will probably go undocumented until we refactor middleware and route handlers to always call next(). This commit shows the refactor for one route handler.

Open

When there is a need to formally update official documentation for new/changed API details, the process would be:

1. Choose a deployment of the new code to generate from. This could be beta, avocado, or even a dev local, but not app. The API cannot be running in production mode.

2. In the api directory run UPDATE_OAS_FILES=1 npm test. This will modify the JSON files with the results of static analysis and the network traffic generated from the backend Jest tests.

3. In the same directory run UPDATE_OAS_FILES=1 npm start. This launches the API in a mode that monitors network traffic and modifies the JSON files accordingly. At this point, running Cypress tests and or manually using the app to activate new API features is a good idea.

4. When finished, commit the modified JSON files to the git repo.