chore(30019): Split the openAPI file

[vanch3d]

See https://hivemq.kanbanize.com/ctrl_board/57/cards/30019/details/

The PR splits the original single YAML document into a structured multi-files system.

Out-of-scope

• IntelliJ (backend) and WebStorm or VSCode (frontend) are using different linting processes for "cleaning" YAML documents and commits will result in changes that are purely aesthetic. A common linting set of rules should be added to the OpenAPI "repo".,

Edge OpenAPI Specifications

Structure

The main document has been split from the original source in order to reduce the size of a single document and to highlight individual points of concern.

The original split was done automatically (using redocly see below) and the files reflects the automation.

openAPI             
├── README.md
├── openapi.yaml        // root document of the OpenAPI specs
├── paths               // list of path files, organised by their route
│   ├── api_v1_auth_authenticate.yaml
│   ├── api_v1_auth_refresh-token.yaml
│   └── ...
│
└── components          // list of reusable definitions, grouped by type
    ├── headers
    │   ├── ETag.yaml
    │   └── ...
    ├── parameters
    │   ├── CombinerId.yaml
    │   └── ...
    ├── schemas
    │   ├── Adapter.yaml
    │   └── ...
    └── ...

There is no reason to maintain such naming convention as we manually add or edit the source.

Usage

The redocly library is used to manage the OpenAPI specs, stored as a split document.

Bundle

Some of the tools handling OpenAPi will be working fine with a split document.
If not, consider bundling it into a single YAML file, using the following command:

redocly split  <source to file>/openAPI.yaml --outDir <destination folter>/

Make sure NOT to commit your bundled document along the split origin; we need to ensure a single source of truth.

Split

To reverse the merge operation and create a split document, the following command will deliver:

 redocly bundle <path to source>/openapi.yml -o <path to dest>/hivemq-edge-openapi-SNAPSHOT.yaml

GitHub guidelines

• The OpenAPI specs define in this document is the only source of truth of the Edge REST API.
• Any change to the document MUST be done on a new clean PR
• Any change to the document MUST be reviewed and approved by both backend and frontend
• Changes to either backend or frontend code MUST NOT be added to the PR proposing the modifications of the specs

[vanch3d]

See ext/openAPI/README.md

[vanch3d]

I'm also in favour of removing the ext/openAPI/hivemq-edge-openapi-master.yaml file, so that we don't maintain two documents that might end up diverging

[codepitbull]

Nice one.
I ran tests locally and all looks good.