[Java] Automatically resolve nested models while remotely referring a model

[ManuAc]

Description

We are using swagger codegen maven plugin to generate models and API clients.

We have a single YAML file for defining all common models and refer them using UR as and when required from all other services. The problem is swagger won't resolve the nested models automatically and it expects all nested models to be defined in the same file (we can reference the remote definition here also but defining the models itself become tedious when there is deep nesting).

Is there any workaround for the same? Can we do something to just reference the root level definition and swagger will automatically resolve all other nested references?

Swagger-codegen version

2.1.6

Swagger declaration file content or url

Example

common.yaml

StatusUpdateRequest:
    description: Status update request
    required:
      - status
    properties:
      status:
        $ref: '#/definitions/Status'

Status:
    description: Status
    type: string
    enum: &status
      - ACTIVE
      - INACTIVE
    default: ACTIVE

Let's say my common.yaml is available at https://example.com/commons.yaml, then my individual service level yaml will be like below

ServiceA.yaml

  /abc/{id}/status:
    parameters:
      - $ref: '#/parameters/IdParam'

    post:
      description: Update status
      operationId: updateStatus
      parameters:
        - name: status
          in: body
          required: true
          schema:
            $ref: '#/definitions/StatusUpdateRequest'
      responses:
        200:
          description: Update done

parameters:

IdParam:
    name:id
    in: path
    required: true
    type: string

definitions:

StatusUpdateRequest:
    $ref: 'https://example.com/commons.yaml#/definitions/StatusUpdateRequest'

But above will fail because swagger won't automatically resolve nested Status definition. We'll have to define Status also in ServiceA.yaml.

Below will work.

StatusUpdateRequest:
    $ref: 'https://example.com/commons.yaml#/definitions/StatusUpdateRequest'

Status:
    $ref: 'https://example.com/commons.yaml#/definitions/Status'

Suggest a fix/enhancement

I think codegen should automatically resolve all nested references. We can use various rules while doing so. For example, if someone wants to refer a model at different location for a nested model, they can explicitly define that along with root-level model definition.

[hkosova]

Does commons.yaml contain the root definitions node? If not, the $refs should look like this:

$ref: 'https://example.com/commons.yaml#/StatusUpdateRequest'

$ref: 'https://example.com/commons.yaml#/Status'

[ManuAc]

Does commons.yaml contain the root definitions node? If not, the $refs should look like this:

$ref: 'https://example.com/commons.yaml#/StatusUpdateRequest'

$ref: 'https://example.com/commons.yaml#/Status'

Hey @hkosova,

Yes commons.yaml does contain root definitions node