swagger-annotations: @Parameter ref field does not work

[brpeterman]

Using Swagger 2.0 annotations, I'm trying to link up operation parameters to parameters defined in components/parameters. My operation looks something like this:

    @GET
    @Produces(APPLICATION_JSON)
    @Operation(
            parameters = {
                @Parameter(ref = "#/components/parameters/lang")
            }
    )
    AddressListResponse getAllAvailableAddresses();

Here's how I'm defining the parameter in question:

	private static Map<String, Parameter> buildParameters() {
		Map<String, Parameter> parameters = new HashMap<>();

		Parameter lang = new Parameter();
		lang.setName("lang");
		lang.setDescription("Language (\"en\") or locale (\"en-US\")");
		lang.setIn("query");
		lang.setExample("en-US");

		parameters.put(lang.getName(), lang);

		return parameters;
	}

	private void configureOpenAPI() {
		OpenAPI api = new OpenAPI();
		Components components = new Components();
		components.setParameters(buildParameters());
		api.setComponents(components);

		OpenAPIConfiguration config = new SwaggerConfiguration()
				.openAPI(api)
				.prettyPrint(true)
				.scannerClass("io.swagger.v3.jaxrs2.integration.JaxrsAnnotationScanner")
				.resourcePackages(resourcePackages);

		try {
			new JaxrsOpenApiContextBuilder()
					.openApiConfiguration(config)
					.buildContext(true);
		} catch (OpenApiConfigurationException e) {
			throw new RuntimeException(e);
		}
	}

The parameter does indeed show up in the components/parameters node, but it does not appear in the operation:

{
  "openapi" : "3.0.1",
  "info" : { ... },
  "tags" : [ ... ],
  "paths" : {
    "/addresses" : {
      "get" : {
        "operationId" : "getAllAvailableAddresses"
      }
    }
  },
  "components" : {
    "schemas" : { ... },
    "parameters" : {
      "lang" : {
        "name" : "lang",
        "in" : "query",
        "description" : "Language (\"en\") or locale (\"en-US\")",
        "example" : "en-US"
      }
    }
  }
}

Am I missing a critical step, or is this broken?

[brpeterman]

After poking around, I've discovered two distinct issues:

1. The format expected by ref in @Parameter is not the same as the one expected elsewhere. In my example above, I used #/components/parameters/lang, but Swagger actually expected just lang.
2. ref does work if I use it for an annotated method parameter. For example:

   AddressListResponse getAllAvailableAddresses(@Parameter(ref = "lang") String lang);

   It does not work in the parameters field of the @Operation or on @Parameter annotations applied to the method.

I believe these are both bugs.

[frantuma]

fixed in #3032

[michele6000]

            parameters = @Parameter(
                    name = "tipoDominio",
                    description = "Tipo di dominio da ottenere",
                    required = true,
                    schema = @Schema(implementation = TipoDominio.class)
            ),
            responses = {@ApiResponse(responseCode = "200",
                    content = {@Content(mediaType = "application/json",
                            schema = @Schema(anyOf = {
                                    DmnReferentiBancheDTO.class,
                                    DmnMotiviDilatoriDTO.class,
                                    DmnStatiPraticheDTO.class,
                                    DmnValuteDTO.class
                            }))})})

This generate this:

  /domini/{tipoDominio}:
    get:
      tags:
      - Domini
      summary: Ottiene un dominio specifico
      operationId: getDominio
      parameters:
      - name: tipoDominio
        in: path
        description: Tipo di dominio da ottenere
        required: true
        schema:
          type: string
          description: Enumerazione dei tipi di dominio
          enum:
          - REFERENTI_BANCHE
          - MOTIVI_DILATORI
          - STATI_PRATICHE
          - VALUTE
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                anyOf:
                - $ref: '#/components/schemas/DmnReferentiBancheDTO'
                - $ref: '#/components/schemas/DmnMotiviDilatoriDTO'
                - $ref: '#/components/schemas/DmnStatiPraticheDTO'
                - $ref: '#/components/schemas/DmnValuteDTO'

But expected is:

/domini/{tipoDominio}:
  get:
    tags:
    - Domini
    summary: Ottiene un dominio specifico
    operationId: getDominio
    parameters:
    - name: tipoDominio
      in: path
      description: Tipo di dominio da ottenere
      required: true
      schema:
        $ref: '#/components/schemas/TipoDominioDTO'
    responses:
      "200":
        description: OK
        content:
          application/json:
            schema:
              anyOf:
              - $ref: '#/components/schemas/DmnReferentiBancheDTO'
              - $ref: '#/components/schemas/DmnMotiviDilatoriDTO'
              - $ref: '#/components/schemas/DmnStatiPraticheDTO'
              - $ref: '#/components/schemas/DmnValuteDTO'

Can anyone help me?