Allow resolution of external references on AsyncAPI file

[lbroudoux]

Reason/Context

As of today, we have a reference resolution mechanism that is used on import time for AsyncAPI spec file. This has been added in #306 in order to support Avro schema references. It also has been used later on for gRPC support addition (one protobuf file may referenced other external protobuf files).

referencing JSON Schema files from OpenAPI files is now a very common practice (though I personally think that you then have to be very cautious on how you manage versioning of everything 😉 )

Description

For unknown reasons, it hasn't been fully applied to AsyncAPI support yet as it has already been done for OpenAPI (see #548)
We should add this full reference resolution mechanism for AsyncAPI.

Implementation ideas

It means that references will be discovered at import time but I see options on how to implement it:

1. Do not modify AsyncAPI file and add extra contracts for JSON Schema to keep everything "as is". This means that during tests we'll have to dereference everything and create an inlined OpenAPI spec in order to ease validation,
2. Dereference everything at import time and modify AsyncAPI file. This means that we'll not have to touch everything during tests and it'll speed up things. However, the user could be lost seeing the import result mentioning only 1 OpenAPI file,
3. Dereference everything at import time and modify AsyncAPI file, but also add extra contracts for JSON Schema to prove we discovered everything.

We'll implement #3 that is the way things have been implemented in #548.

[lbroudoux]

I've produced a sample for such a case here: https://github.com/microcks/microcks/raw/1.7.x/webapp/src/test/resources/io/github/microcks/util/asyncapi/user-signedup-json-ref-asyncapi.yaml

If you'd like to check, please import the file above using a regular importer job that connects to GitHub. It should discover the AsyncAPI schema as well as an additional JSON Schema. See capture below:

You can check the microcks pod logs that should display the following messages where the relative reference is resolved at the moment you launched the import:

16:13:09.329  INFO 15232 --- [080-exec-4] i.g.microcks.service.ServiceService      : Importing service definitions from https://github.com/microcks/microcks/raw/1.7.x/webapp/src/test/resources/io/github/microcks/util/asyncapi/user-signedup-json-ref-asyncapi.yaml
16:13:10.507 DEBUG 15232 --- [080-exec-4] g.m.u.RelativeReferenceURLBuilderFactory : Returning a SimpleReferenceURLBuilder
16:13:10.510  INFO 15232 --- [080-exec-4] i.g.m.u.MockRepositoryImporterFactory    : Found an asyncapi: 2 pragma in file so assuming it's an AsyncAPI spec to import
16:13:10.561 DEBUG 15232 --- [080-exec-4] i.g.microcks.service.ServiceService      : Service [User signed-up API, 0.1.0] exists ? false
16:13:10.581  INFO 15232 --- [080-exec-4] i.g.microcks.util.ReferenceResolver      : Downloading a reference file at https://github.com/microcks/microcks/raw/1.7.x/webapp/src/test/resources/io/github/microcks/util/asyncapi/user-signedup.json
16:13:12.869 DEBUG 15232 --- [    task-1] i.g.m.l.ServiceChangeEventPublisher      : Received a ServiceChangeEvent on 64395f767061a54dd04d5034

Also, when looking at the AsyncAPI contract, reference to the JSON schema that was $ref: "./user-signedup.json" at first should have been re-referenced to the new JSON schema name as recorded into Microcks so that latter validation can be safely executed. See final results you should see below:

components:
  schemas:
    UserSignedupEvent:
      type: object
      allOf:
        - $ref: "User+signed-up+API-0.1.0-user-signedup.json"