Show API documentation at /api/

[mrkvon]

Proposed Changes

• auto-generate API documentation in OpenAPI format with npm run generate-api-docs (the documentation isn't perfect, but it's good enough, much better than doing it manually) using swagger-autogen
• display API documentation with Swagger-UI on /api/ path
• hide the API documentation behind feature flag { featureFlags: { apidocs: true } } in ./config/env/local.js
  • by default it shows in development, but not in production
• generate up-to-date documentation before every commit with husky
• additional fix: update leaflet-active-area library to latest version from npm; otherwise webhooks fail to install node_modules when they try to fetch the library from github, because of some weird ssh authentication reason.

The OpenAPI json, and files for Swagger-UI are stored in /apidocs/ folder. It can be moved elsewhere if somebody prefers

Motivation

For people who want to develop e.g. mobile app on top of Trustroots API, this can be useful resource

Testing instructions

1. Update node_modules by running npm ci

2. Try to delete /apidocs/openapi.json, then run npm run generate-api-docs, and it should re-appear

3. Run the app locally, and go to http://localhost:3000/api/, and you should see
   

4. If running the whole app locally is too much for you, you can

• install e.g. http-server: sudo npm install -g http-server
• in terminal, go to Trustroots repository that you cloned locally
• go to this branch git switch api-docs
• cd apidocs/
• run the server with command http-server
• in your browser, go to http://localhost:8080, and see the documentation

[JohnvdWaeter]

Tried it locally, looks fine to me (although I have no idea what I should see :) )

[mrkvon]

Tried it locally, looks fine to me (although I have no idea what I should see :) )

If you go to http://localhost:3000/api/, you should be able to see the Swagger documentation of Trustroots API

[JohnvdWaeter]

Yes, that works!

[mrkvon]

Ok, great! Thank you for testing @JohnvdWaeter!
I'd like to give @robokow opportunity to deploy #2649 separately, and when that one is in production, let's merge this one. Please, @robokow ping me here when you deploy #2649. Thanks!

[mrkvon]

Proceeding with the merge, since b7b9725 was deployed. ✅