[Spike] Merge OpenAPI Specs

[hspedro]

➕ Enhancement Request

Timebox: 2 hours

Problem related to enhancement request

Kong will likely expose a single OpenAPI YAML with all product specifications merged. Thus, merge the current specs of the project, taking into account collision handling. Either way, the parser will concatenate the YAML structure into a single intermediate structure, so this will not conflict with the work that we are doing.

Sought-for solution

• Check openapi-tools for existing tooling

[hspedro]

Testes with two existing tools: redocly and openapi-merge.

Redocly

✅ Open-source ✅ Installed via npx or docker ✅ Accept both JSON and YAML on the join command ❌ join command is experimental ❌ join does not handle conflicts very well: it will point it out for the user to resolve, the options to resolve automatically are very limited

openapi-merge

✅ Open-source ✅ Installed via npm ✅ Accepts both JSON and YAML in combining ✅ JSON config file on how to handle conflicts ❌ Server URLs are not merged, first one is adopted (non-configurable) ❌ Description merge options are limited

For example:

npx openapi-merge-cli

With the following config:

{
    "inputs": [
        {
            "inputFile": "block-storage.openapi.yaml",
            "dispute": {
                "prefix": "blockStorage"
            },
            "pathModification": {
                "prepend": "/blockStorage"
            },
            "description": {
                "append": true
            }
        },
        {
            "inputFile": "virtual-machine.openapi.yaml",
            "dispute": {
                "prefix": "virtualMachine"
            },
            "pathModification": {
                "prepend": "/virtualMachine"
            },
            "description": {
                "append": true
            }
        }
    ],
    "output": "./storage-vm.yaml"
}

Produces the output as:

openapi: 3.0.3
info:
  title: Block Storage API Product
  description: |-
    Block Storage API Product Documentation

    Virtual Machine Api Product
  contact:
    name: Tribo IAAS Cloud
    url: 'https://github.com/luizalabs'
    email: lia.furtado@luizalabs.com
  version: 1.52.0
servers:
  - url: 'https://api-block-storage.br-ne-1.jaxyendy.com'
tags:
  - name: healthchecks
    description: healthchecks
  - name: usage
    description: usage
  - name: snapshots
    description: snapshots
  - name: volume-types
    description: volume types
  - name: block-storage
    description: block storage
  - name: instances
    description: instances
  - name: keypairs
    description: keypairs
  - name: instance-types
    description: instance types
  - name: images
    description: images
paths:
  /blockStorage/v0/healthcheck:
     ...
  /virtualMachine/v0/usage:
     ...