[SPIKE] Resolve `$ref` in api/controller/route specs

[bajtos]

At the moment, our code processing Swagger/OpenAPI Spec does not support $ref references, we assume all entities have been denormalized/dereferenced. IMO, this is a severe limitation because even the simples CRUD-based REST APIs usually reuse model (response object) definitions.

We should investigate how to support $ref in all places allowed by OpenAPI spec. Let's limit the scope to relative references only (e.g. #/definitions/User) and exclude external references (e.g. http://json-schema.org/address).

Acceptance Criteria

• Establish agreement of the virtual OpenAPI Spec / $ref resolution
• What's the target OpenAPI Spec we're resolving against.
• Consistency between top-down and bottom-up approach
• Contributing Artifacts: Controller, Models, OpenAPI Spec, others?

[stale]

This issue has been marked stale because it has not seen activity within six months. If you believe this to be in error, please contact one of the code owners, listed in the CODEOWNERS file at the top-level of this repository. This issue will be closed within 30 days of being stale.

[virkt25]

@bajtos @jannyHou is this still an issue with the migration to OAS3?

[raymondfeng]

swagger-parser now supports openapi 3.0 with dereference. We should use it.

See https://github.com/BigstickCarpet/swagger-parser/blob/master/docs/swagger-parser.md#dereferenceapi-options-callback