chore: refactor lsg asyncapi schema

[justandras]

About the Contributor

This pull request is posted on behalf of the BBC.

Type of Contribution

This is a: Code improvement / Documentation improvement

Current Behavior

1. Currently the Live Status Gateway's AsyncApi schemas do not reuse definitions, it's hard to maintain.
2. Examples have to be defined inline, without the ability to include already defined examples in a nested object.
3. All messages are logically grouped in the same / channel
4. Types for messages to be sent by the client are not generated

New Behavior

1. Added a script to resolve example references as it's currently not supported by our AsyncApi version.
2. Split up the schemas into smaller chunks, established inheritance between schemas to minimize duplicate definitions.
3. Introduced the concept of channels to organize the schemas, improve documentation readability
4. Added a script that creates a single asyncapi.yaml file for better compatibility with tools like Postman and other parsers.
5. Types are now generated for messages that are send by the client.

Testing

• I have added one or more unit tests for this PR
• I have updated the relevant unit tests
• No unit test changes are needed for this PR

Affected areas

This PR is only an internal refactor of the schemas, there is no breaking change in the generated types.

This PR affects:

1. The schema source files for the Live Status Gateway.
2. The type, docs and server generation for the Live Status Gateway API.

Time Frame

This Refactor is critical for us, we have other PRs, feature request that depend on it.

Other Information

Due to AsyncApi limitations, some types now have to have an optional property additionalProperties. This will remain unused, there is no clean workaround to have inheritance between schemas that we know of and disallow additionalProperties at the same time.

We the SuperFly team have discussed it internally and feel like it's a worthy compromise.

Status

• PR is ready to be reviewed.
• The functionality has been tested by the author.
• Relevant unit tests has been added / updated.
• Relevant documentation (code comments, system documentation) has been added / updated.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ianshade]

Reviewed, and tested some of it locally. I'm happy with the changes