OpenAPITools / OpenAPITools/openapi-generator

[BUG] [JAVA] [JAXRS-SPEC] jaxrs-spec generator should support the vendor extension `x-field-extra-annotation` on OPERATION_PARAMETER level

Open
#22,956 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Issue: Bug
Dominant language
Java
Stars
26.8k
Forks
7.7k
PR merge metrics
PR metrics pending

Description

Bug Report Checklist
  • Have you provided a full/minimal spec to reproduce the issue?
  • Have you validated the input using an OpenAPI validator?
  • Have you tested with the latest master to confirm the issue still exists?
  • Have you searched for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Sponsorship to speed up the bug fix or feature request (example)
Description

According to the docs for the jaxrs-spec generator it should support the x-field-extra-annotation extension on the OPERATION_PARAMETER level. This is false.

The generated code looks something like this:

@Path("/asset")
@jakarta.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen", comments = "Generator version: 7.19.0")
public interface AssetApi {
    @GET
    @Path("/{id}")
    @Produces({ "application/json" })
    Response getAsset(@PathParam("id") UUID id,@HeaderParam("X-Locale")   String xLocale);
}

It should look like this instead.

@Path("/asset")
@jakarta.annotation.Generated(value = "org.openapitools.codegen.languages.JavaJAXRSSpecServerCodegen", comments = "Generator version: 7.19.0")
public interface AssetApi {
    @GET
    @Path("/{id}")
    @Produces({ "application/json" })
    Response getAsset(@PathParam("id") @org.hibernate.validator.constraints.UUID(version = {7}) @jakarta.validation.constraints.NotNull UUID id);
}
openapi-generator version

7.19.0

OpenAPI declaration file content or url
paths:
    /asset/{id}:
        get:
            tags:
                - asset
            operationId: getAsset
            parameters:
                - $ref: "#/components/parameters/Identifier"
            responses:
                "200":
                    description: Asset found
components:
    parameters:
        Identifier:
            name: id
            in: path
            required: true
            schema:
                type: string
                format: uuid
                nullable: false
            description: |
                The unique identifier of the resource. Must be a valid UUID.
            # noinspection YAMLSchemaValidation
            x-field-extra-annotation:
                - "@org.hibernate.validator.constraints.UUID(version = {7})"
                - "@jakarta.validation.constraints.NotNull"
Generation Details

I use maven 3.9.11 and java 21 to generate my server files. The configuration is completely in the maven plugin under <configOptions>. For readability, these are the parameters I configured that affect the code generation:

generatorName: jaxrs-spec
configOptions:
    library: quarkus
    sourceFolder: src/gen/java/main
    apiPackage: com.test
    dateLibrary: java8
    modelPackage: com.test.model
    returnResponse: true
	
Steps to reproduce
  • generate the code
  • look into the generated AssetApi.java file and see that the annotations that should be on the getAsset method are missing.
Related issues/PRs
Suggest a fix

The template for the jaxrs-spec generator looks like this:
JavaJaxRS/spec/queryParams.mustache

{{#isPathParam}}@PathParam("{{baseName}}"){{#useBeanValidation}}{{>beanValidationPathParams}}{{/useBeanValidation}}{{#useSwaggerAnnotations}}{{#description}} @ApiParam("{{.}}"){{/description}}{{/useSwaggerAnnotations}}{{#useMicroProfileOpenAPIAnnotations}}{{#description}} @org.eclipse.microprofile.openapi.annotations.parameters.Parameter(description="{{.}}"){{/description}}{{/useMicroProfileOpenAPIAnnotations}} {{{dataType}}} {{paramName}}{{/isPathParam}}

In comparison the template for spring looks like this:
JavaSpring/queryParams.mustache

{{#isPathParam}}{{#vendorExtensions.x-field-extra-annotation}}{{{.}}} {{/vendorExtensions.x-field-extra-annotation}}{{#useBeanValidation}}{{>beanValidationPathParams}}{{/useBeanValidation}}{{>paramDoc}} @PathVariable("{{baseName}}"){{>dateTimeParam}}{{#isDeprecated}} @Deprecated{{/isDeprecated}} {{>optionalDataType}} {{paramName}}{{/isPathParam}}

The jaxrs-spec template seems to be missing the {{#vendorExtensions.x-field-extra-annotation}} templating parameter.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with modules/openapi-generator/src/main/resources/JavaJaxRS/spec/pathParams.mustache and compare it with the referenced JavaSpring/pathParams.mustache template. Run the supplied OpenAPI declaration through the jaxrs-spec generator, then verify that the generated AssetApi.java includes both x-field-extra-annotation values on the path parameter.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, tooling
Issue type
Bug
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.