zeus-proto

Zeus

The goal of this project is twofold;

1. To have a centralized repository with platform agnostic API schema contracts, versioning and history, for use with a 'contract-first' development approach.
2. To create both javascript and php boilerplate code that applications will use when serializing / deserializing the API contract data to validate its correctness.

Schemas

The schemas found in the schemas folder are language agnostic and are either Protobuf or OpenAPI / JSON Schemas. Protobuf has been chosen as it can represent a wide range of technologies including GRPC and Kafka - which is the underlying messaging bus for the entire internal CBH banking infrastructure. OpenApi / JSON Schema has been chosen for the remaining HTTPS requests between the remote frontend applications and backend microservices exposing 'external' APIs.

Protobuf

nvm is a pre-requisite

To generate the code for the Protobuf schemas, run the following commands:

nvm use
npm i
docker-compose up

OpenAPI

The javascript part of this library uses OpenAPI schema 3.0.3 due to limitations of the available tooling at creation. It is planned to eventually migrate to at least OpenApi schema 3.1 as it has full compatibility with JSON Schema draft 2020-12.

As such, OpenAPI schemas should be created with 3.1 in mind.

JSON Schema

The JSON Schema part of this library is using draft 2020-12.

Interoperability

With OpenAPI 3.1 and JSON Schema draft 2020-12, the schema object is now an 'extended subset of the JSON Schema Specification'. As such, eventually JSON Schemas can be used in their entirity in this part of the OpenAPI specification.

With the current use of OpenAPI 3.0.3 and JSON Schema draft 2021-12, there are some minor incompatibilities. Current limitations are listed below.

Current limitations

Some of the tooling has not yet implemented OpenAPI 3.1 or JSON Schema draft 2020-12, so there are some workarounds in place;

• $id tags have been removed for now as an underlying library json-schema-ref-parser doesn't implement $id logic correctly yet.
• $refs are relative paths instead of referencing full $ids due to the issue above.
• $refs in some cases are relative to the root directory and other times relative to their parent directory.
• There is an intermediary build step json-generate-schemas which creates de-referenced schemas for the reasons above.
• OpenAPI validation complains of $schema properties as they as seen as additional properties in version 3.0.3, which are forbidden.
• OpenAPI schemas aren't as modular as possible due to the underlying json-schema-ref-parser library issues.
• OpenAPI currently doesn't support nested objects in query parameters, which means it is impossible to describe ?filter[search][eq]=something

Installation

Install protoc either directly as explained here here or as a docker image

Then install the javascript development packages;

nvm use
npm i

And the php development packages; TODO

Quick generation

To generate the validation code, dereferenced OpenAPI schemas and more, simply run the following command;

npm run generate

This command simply combines the following commands;

Boilerplate Typescript

Typescript boilerplate code is generated for each micro-service using javascript npm commands via another CBH code generation library.

Generation

To generate the javascript validation module files and the typescript definition files, run the following command;

npm run generate-json

Compiled output will be output to lib/microservice-name/.

Publishing

TODO

OpenAPI

The fully dereferenced OpenAPI schema for each micro-service is generated using javascript npm commands.

Generation

The intermediary JSON Schema must be compiled first by the npm commands above.

To generate the micro-service openapi.json files, run the following command;

npm run generate-openapi

Compiled output will be output to lib/microservice-name/.

Validation

The library can validate all the generated .openapi.json files after generation with the following npm command;

npm run openapi-validate

Boilerplate PHP

Php boilerplate code is generated for each micro-service using php composer commands.

Installation

TODO

Generation

TODO Compiled output will be output to lib/php/.

Publishing

TODO

Resources

OpenAPI 3.0.3 Spec JSON Schema TS Proto CLI options Migrating from OpenAPI 3.0 to 3.1