[Epic] 3.4: Self-documenting Rest APIs

[mfw78]

Epic label: E:3.4 Self-documenting Rest APIs Planned start date: 01/12/2023 Due date: 31/12/2023

Summary

Within the services repository, there are two Rest APIs that are exported in openapi.yml, notably in the orderbook and the solvers crates.

When analysing these Rest APIs, it was identified that:

1. The openapi.yml that is used by downstream consumers is not programmatically bound / generated via CI/CD, leading to error-prone manual maintenance / updating.
2. The solvers crate makes use of axum / tower, as opposed to the orderbook crate that makes use of warp.

Acceptance Criteria

On completion of this refactor, the Rest APIs shall:

1. Absent a compelling argument against, use the same dependency for running the Rest API.
2. Have their OpenAPI specification programmatically generated.
3. Have their generated OpenAPI specification thoroughly tested against the respective service for completeness / accuracy.

Tasks

• [ ] research: axum vs warp (unify, or not?)
• [ ] research: suitability of utoipa for openapi generation
• [ ] research: api property testing with schemathesis

[squadgazzz]

We can consider using utoipa, but this project(https://github.com/ProbablyClem/utoipauto) clearly describes the main drawback of the lib's current state. But looks like this project is not currently ready to work with external types: https://github.com/ProbablyClem/utoipauto/issues/4 meaning that schemas should be specified manually, which is also prone to human errors.