...
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.
...
When there is a need to formally update official documentation for new/changed API details, the process would be:
Choose a deployment of the new code to generate from. This could be beta, avocado, or even a dev local, but not production.
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.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.When finished, commit the modified JSON files to the git repo.
| Note |
|---|
The generated documentation will include the contents of requests and responses made while the API runs with the env var set. Use caution to avoid including sensitive or inappropriate data. This is why the configuration is to never gather network data when running in production mode. |