Expectations around OpenAPI usage

[pahjbo]

Although it has been agreed to proceed in producing OpenAPI definitions for standards that define interfaces, there is no written guidance on how this should be done. Topics such as

• modularisation of the OpenAPI definitions (difficult)
• tools to be used to syntactically validate the definitions (should be added to the GitHub CI)
• generation of documentation from the OpenAPI definitions (should be the minimal use that the definitions are put to, again should be part of the GitHub CI
  • how to distribute this documentation?
• how to distribute the OpenAPI definitions.

Harder validation questions

• how to validate that the standard text and the OpenAPI definitions agree?
  • possibly easier for existing standards where server side implementations (written against the document) exist - an OpenAPI client generator could be used.
  • in future what is the policy if there is found to be disagreement between OpenAPI definition and document text (probably to decide on case by case basis)?

[pahjbo]

Incidentally my suggestion would be to experiment with CI before beginning to write something down