Resolve of parameter $ref definition

[nicolaideffremo]

The contract below does not resolve as I would expect, when parsed with the resolve option. The parameter reference is inlined and the components section kept as is. I would expect to keep the reference and in the case of a file or remote reference replace with a local reference.

openapi: 3.0.3
info:
  title: technical-definitions
  description: Commons technical definitions
  version: 1.0.0
servers:
  - url: https://
paths:
  /components/parameter:
    get:
      tags:
        - example
      operationId: getExampleById4
      parameters:
        - $ref: '#/components/parameters/Parameter'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
components:
  parameters:
    Parameter:
      name: id
      in: query
      description: The ID of the example to retrieve
      required: true
      style: form
      explode: true
      schema:
        type: string

This is reproducible with the parser configuration below:

var parser = new OpenAPIV3Parser();
var options = new ParseOptions();
options.setResolve(true);

parser.readContents(contract, Collections.emptyList(), options);

[daniel-kmiecik]

@nicolaideffremo thanks for the report. I don' see anu issue here. Here's a concise explanation:

• setResolve(true) tells the Swagger parser to resolve top-level $ref references, but nested $ref inside resolved objects remain untouched (they stay as $ref).
• setResolveFully(true) tells the parser to recursively resolve all $ref references, including any nested ones, so you get a fully dereferenced OpenAPI model.

In short:
resolve = shallow, resolveFully = deep.

To see the difference you can play with the test method testFull() in the OpenAPIV31ParserFullResolveFullyTest class.

If you still see the problem please create a ticket giving more details (steps to reproduce) and please highlight the problem.

[nicolaideffremo]

@daniel-kmiecik Thanks for the quick reply.

I do not get that point fully. Maybe I can make my example more clear. The contract with a file reference to a parameter will produce a duplication of the parameter resolution. Parameter will be inlined and added to #/components/parameters.
That does not fit the description of resolve, especially point 4. "replace the remote/relative reference with a local reference". So the result looks like this:

openapi: 3.0.3
info:
  title: technical-definitions
  description: Commons technical definitions
  version: 1.0.0
servers:
- url: https://
paths:
  /components/parameter:
    get:
      tags:
      - example
      operationId: getExampleById4
      parameters:
      - name: id
        in: query
        description: The ID of the example to retrieve
        required: true
        style: form
        explode: true
        schema:
          type: string
      responses:
        "200":
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
components:
  parameters:
    Parameter:
      name: id
      in: query
      description: The ID of the example to retrieve
      required: true
      style: form
      explode: true
      schema:
        type: string

I investigated the behaviour a bit more and noticed this place in the code of the OperationsProcessor.

    public void processOperation(Operation operation) {
        if (operation.getParameters() != null) {
            for (Parameter parameter : operation.getParameters()) {
                parameterProcessor.processParameter(parameter);
            }
        }
        final List<Parameter> processedOperationParameters = parameterProcessor.processParameters(operation.getParameters());
        if(processedOperationParameters != null) {
            operation.setParameters(processedOperationParameters);
        }

...

It looks to me like the parameter is processed twice. The first call correctly adjust the reference to the local reference. The second processing will inline the parameter and replace the correctly resolved parameter with an inlined one.

Can you help me understand, if this is really the intended behaviour? Your explanation confused me.

[nicolaideffremo]

@daniel-kmiecik Have you had time to look at the additional context? I still think this is a bug and does not align with your spec of the parser behaviour.

[marcelstoer]

@ewaostrowska Since you accepted #2216 as a bug, I'd appreciate if you could reevaluate this one as well. They are both issues of the same kind IMO.