🛠️ [TASK] : Add OpenAPI linting to our CI process.

[stevenj]

Summary

Add OpenAPI linting for catalyst-gateway but in a way we can easily re-use on other targets.

Description

We want to add openapi-linting to catalyst-gateway.
Catalyst-gateway auto generates the OpenAPI spec document, but we still need to ensure it follows best practice.
This will help keep our documentation of high quality and ensure we don't have any issues that could cause problems for people trying to use our specifications or documentation.

We should use: https://github.com/stoplightio/spectral
It has a feature to allow it to lint any json/yaml document with custom rules. As we want to use jason-schema to define forms for catalyst-gateway this could be a useful re-usable too to enforce consistency or limit our forms to features we support vs the entire json-schema feature set.

Tasks

• make a builder (or add to one) in cat-ci that incorporates spectral and any rulesets we want (both third party and in-house).
  • Minimum 3rd party rule sets owasp top 10 and documentation others listed in the spectral repo should be evaluated for usefulness given our projects. This might be simply a target that exports the necessary ruleset artefacts, so they can be used consistently in other parts of the build.
  • It might be easiest to just use the binary install method: https://meta.stoplight.io/docs/spectral/b8391e051b7d8-installation and integrate directly into the rust builder as our api's are generated from rust.
• Generate the OpenAPI spec during the build step of catalyst-gateway, after the binary images themselves have been built.
• Then add a check to run the linter against them with the necessary rules. (If possible this could be a UDC to reduce boiler plate).
• Correct any issues the linter picks up in the catalyst-gateway API.
  • If the issue is with how Poem generates its specification we will need to work out how to make poem produce a compliant document, or temporarily disable the failing lint (or set it to a warning level) and then raise a ticket to fix poem upstream so it can produce better specifications.