OpenAPITools / OpenAPITools/openapi-generator

[doc] [java/spring] x-YYY-extra-annotation doc is misleading

Open
#15,858 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

Description

the current java/spring doc reads:

List of custom annotations to be added to YYYY

So i was thinking: ok, i can write a yaml list if all my annotations that i want to add. eg.

      properties:
        foo:
          type: string
          x-field-extra-annotation:
            - "@MyCustomAnnotation1"
            - "@MyCustomAnnotation2"

WRONG

First one needs to understand that annotation in x-field-extra-annotation has nothing to do with java annotations even though the description suggests that IMO.

Second, there is no "List" here in a syntactical yaml/json sense, rather this extension may be used to add a list of java annotation there, but also a myriad of other things.

What this really does, is:

  1. create a json-ish string from the value of x-field-extra-annotation (ie drop the quotes, replace : -> = )
  2. put that as a text above the field

Hence, a more fitting name to the current behavior would be x-field-extra-text-above.

example:

        value:
          x-field-extra-annotation:
            foo:
              bar:
                 - 123
                 - ASDASD

will do this:

  {foo={bar=[123, ASDASD]}}
  private String value;
openapi-generator version

6.6.0

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

Locate the Java/Spring documentation for x-field-extra-annotation and compare its wording with the behavior and examples described in the issue. Update the explanation so it does not imply a YAML list of Java annotations and accurately describes the generated text; the documentation examples should reflect the shown output.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, spring
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.