🛠️ [TASK] : Find out why our OpenAPI docs display poorly

[stevenj]

Summary

Fix OpenAPI documentation viewing

Description

As we build out catalyst Voices, being able to easily and comprehensively review the rendered openAPI documentation is critical.
This task is to find out why the OpenAPI docs render poorly in catalyst-voices, and fix them.
There should be an example of open-api docs rendering in Cat-CI, using a sample OpenAPI doc.

Tasks

• Add Earthfile to: examples/openapi which includes OpenAPI Linting, and Rendering of the docs.
  • Have a look in catalyst-voices how it both lints open-api and andl renders docs.
  • Use the example file in that path as the example api document for this task.
• Embed the example OpenAPI documentation inside the cat-ci docs examples in : docs/src/appendix/examples
  • Again, check catalyst-voices for how the open-api docs are embedded there, and replicate here as an example.
• Work out why they render poorly, and work out a strategy to correct it.
• Correct the documentation rendering so it is easier to review.
• Once this is complete, Integrate updated OpenAPI docs into catalyst-voices.
  • 🛠️ [TASK] : Documented Public Open API Definition for cat-data-service. catalyst-voices#887

Note: We curently use : https://stoplight.io/open-source/elements
This was chosen because its freely deployable, supports the latest OpenAPI standards, and seems to have the nicest look/feel as at the last time we reviewed it. This task should include updating to the latest version of this, and if you think a better viewer has come along, you can present it to the team at one of the tech meetings for discusion and consideration for replacement.