Skip to main content

[Operational] README

Federation EWBI Openapi Spec​

Here contains:

  • The official Federation EWBI (East-West Bound Interface) API spec as OPG.04_EWBI_Federation_API_v1.4.0-official.yaml (source, download)
  • A modified version as OPG.04_EWBI_Federation_API_v1.4.0.yaml
  • A Makefile to generate both API struct models and golang Echo server stubs.

Generators​

We use two generators as part of the doc/fedapi files:

  • oapi-codegen to generate Echo server stubs. Unfortunately this generator does not generate structs for callback objects, so is not used for generating struct objects. This generates a single file, pkg/mc/federation/ewbi-server.gen.go.

  • openapi-generator for generating API structs. This tool seems to be better supported and more fully featured, but it's targeted towards client generator, and thus has no server-side stubs generator. This generates all the files in pkg/fedewapi.

To generate, just run

make

for correct work needed:

  • go install golang.org/x/tools/cmd/goimports@latest
  • go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@v1.12.4

Changes​

We have several modifications to the official yaml which are documented as patches in the patches directory. To add a new change:

  • First make a copy of the current yaml OPG.04_EWBI_Federation_API_v1.4.0.yaml and OPG.04_EWBI_Federation_API_v1.4.0_-_official.yaml
  • Make your changes to OPG.04_EWBI_Federation_API_v1.4.0.yaml.yaml
  • Generate a diff of your changes (number is important to apply patches in order) 
    diff -au OPG.04_EWBI_Federation_API_v1.4.0.yaml.last OPG.04_EWBI_Federation_API_v1.4.0.yaml > patches/##-my-change-desc.patch

Updating Official Spec​

If updating the official spec:

  • Copy new spec to OPG.04_EWBI_Federation_API_v1.4.0_official.yaml
  • Make sure to convert above file from DOS format to Unix line endings
  • Copy official to local: 
    cp OPG.04_EWBI_Federation_API_v1.4.0_official.yaml OPG.04_EWBI_Federation_API_v1.4.0.yaml
  • Reapply our patches (11, 05, 02) 
    patch < patches/*
    For next updates logic from patches
    • remove all oneOf, anyOf, allOf
    • remove all invalid references as # $ref: 'https://github.com/camaraproject' to type: object (JSON) If some our changes are upstreamed, the patch file for that change can be removed. First version patches 11, 05, 02, after update was created - updated OPGv1.4.0.patch (contains all earlier and new) - better to check manually and follow the discribed logic to avoid new invalid fields