Tool to generate OpenAPI / JSON Schema / TS protocol definitions

[pablohoch]

An extended version of the tool currently used to generate the TypeScript protocol types for the RSL UI. Includes documentation for some RSL APIs.

Outputs:

• JSON Schema (version 2020-12)
• OpenAPI 3.0.3 (supported by most tools)
  • Limitations:
    • Descriptions of fields with custom types are currently missing, because custom types are referenced using $ref and no other sibling elements are allowed in OpenAPI 3.0
    • Matching union type tags are not enforced by the schema
    • Only one example per type is allowed (the first example is used, all others are ignored)
• OpenAPI 3.1.0 (better support for our union types, documentation for $ref fields, unlimited examples)
• TypeScript types

Inputs:

• FlatBuffers schema files
• Documentation for the types + paths/operations (YAML files in docs/api)
  • Missing files in docs/api/schemas for new namespaces are automatically created
  • Missing types/fields in docs/api/schemas are automatically added

Configuration is currently in tools/protocol/protocol.config.yaml.

Usage:

• In tools/protocol run: pnpm start
  • To generate the RSL UI TypeScript definitions run: pnpm start rsl.config.yaml
• The files in docs/api/schemas are updated with new types (and TODO placeholders)
• Output OpenAPI + JSON Schema files are placed in docs/generated
• See tools/protocol/README.md for more information

Artifacts (generated by CI):

• OpenAPI 3.1: /web/openapi.yaml (served via HTTP at /openapi.yaml)
• OpenAPI 3.0: /web/openapi-3.0.yaml (served via HTTP at /openapi-3.0.yaml)