feat(cmd-api-server): aggregate swagger.json endpoints

[petermetz]

Is your feature request related to a problem? Please describe.

swagger and OpenAPI are synonymous. Swagger around version 2 was renamed to OpenAPI, which today is at its third major release (which is the one we are using). The terminology hasn't been updated in all their tooling yet and therefore here and there we refer to the open API spec files as swagger files, but the reader should always be aware that these mean the exact same file.

Currently, we use OpenAPI, but we do not have the swagger.json file exposed which would allow people to inspect the generated documentation for all the endpoints that we through the Swagger Editor 1, 2

Describe the solution you'd like

1. Have two endpoints implemented in the package cmd-api-server. Both of which are to serve GET requests and return the contents of a openapi-spec.json document that is the aggregate of the openapi-spec.json documents of the plugins exposing web services that the API server has installed (tip: use the plugin registry to fetch a list of web service plugins, there's examples for this in the api-server.ts file within the cmd-api-server package.
2. One of the endpoints is to return the aggregate openapi-spec.json document for the current Cactus API server instance only (which means that it provides a view of the web services available on that Cactus Node that the API server is a part of)
3. The second endpoint is to provide an openapi-spec.json document similarly to the first one but this one is to include everything from the entire consortium, meaning that if there's a consortium of two members and their nodes provide different web services (let's say, connectors for different ledgers) then in this second endpoint the returned spec document should contain both of these.

Dealing with conflicting web service paths

If two nodes have the same plugin installed but with different configuration, then we have a problem for endpoint 2) because these will get into a conflict based on their matching paths.

One way of dealing with this is to just let it happen meaning that based on the path the two web services will get collapsed into one as far as the developer is concerned. This is not as bad as it sounds because it still provides a complete and accurate view of what web services of the consortium as a whole are available for developers to be used. The only information that is lost is the fact that there are two plugins on different needs that can be used for different things such as if both nodes have a Besu ledger connector pointing to different Besu ledgers (so 2 separate ledgers are in this mental picture).

A better way of dealing with the problem stated above would be to add an extension property 3 to our OpenAPI spec files that encodes the information that is lost during the assembly of the aggregate OpenAPI spec file (as explained in the paragraph above).
The extension property would have to be an array type so that it's well defined how the values of the extension property can be concatenated into a single one (by joining the arrays)
The values within the extension property's array could be either the plugin instances, or the Cactus node IDs as specified in the Consortium database. These values would then be able to power the routing mechanisms involved in making sure that the it is possible to disambiguate requests sent to the otherwise identical ledger plugins in the example above (2 besu ledger connectors, 2 besu ledgers).

The extension property to be defined as shown here:

{
    "openapi": "3.0.3",
    "info": {
        "title": "Hyperledger Cactus API Server",
        "description": "Interact with a Cactus deployment through HTTP.",
        "version": "0.0.1"
    },
    "servers": [
        
    ],
    "components": {
        "schemas": {
            "GetConsortiumOpenApiSpecResponse": {
              "type": "object",
              "properties": {
                "openapi": {
                  "description": "The specification's version of the document being returned.",
                  "type": "string"
                } 
              }
            },
        }
    },
    "paths": {
        "/api/v1/get-consortium-open-api-spec": {
            "get": {
                "summary": "Obtains an OpenAPI specification file describing all API web services provided by the entire Cactus consortium combined.",
                "parameters": [],
                "x-hyperledger-cactus-node-ids": [
                  "8b8fa207-0116-46d1-a777-ac2deb544281",
                  "e4619e9e-1c2d-4104-9776-1983b99d8e7d"
                ],
                "x-hyperledger-cactus-node-hosts": [
                  "https://node.of-some-consortium-member.example.com",
                  "https://node.of-some-other-consortium-member.example.com",
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/GetConsortiumOpenApiSpecResponse"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

Describe alternatives you've considered

Considered having this in the consortium plugin instead, but ultimately decided that it would be better in the API server package.
Willing to hear opinions to the contrary of course. It's hard to get these things right at the drawing table.

cc: @takeutak @sfuji822 @hartm @jonathan-m-hamilton