Documented Annotations are not visible

[roeltje25]

We have annotations in our project that define some security constraints. The annotation is even used with @NameBinding in order to enforce the constraints. The annotation is additionally annotated with the @Documented meta-annotation so the Javadoc would show it.

What we would want is that the swagger documentation would also make mention of this annotation. perhaps even listing the javadoc comment that is present on top of the annotation. JAX-RS analyzer is currently not handling such annotations. Perhaps this could be incorporated in a future release? Perhaps guarded by a switch if not everybody likes having such annotations mentioned.

[sdaschner]

Sounds interesting.

How do you think the Swagger output should look like? Are there appropriate Swagger properties for that? Or in other words: what kind of information should the annotation represent then? The thing is that it should reflect generally applicable information, so something that is not just a home-grown solution but can fit for all kind of purposes.

[roeltje25]

Well, I would suggest to use the vendor extension mechanism for that. For example, assume we have annotated a resource or a resource method with the documented annotation @GreatOperation(yell="WOW!") and also assume the annotation is written as:

/**
 * This is a great operation!
 */
@Documented
@Target({ TYPE, METHOD })
@Retention(RetentionPolicy.RUNTIME)
public @interface GreatOperation{
  String yell() default "":
}

then in swagger you could have something like:

"/pet":{  
  "post":{  
    "summary":"Add a new pet to the store",
    "description":"",
    "operationId":"addPet",
    "x-annotation-great-operation": { 
      "description":"This is a great operation!", 
      "verbatim":"@GreatOperation(yell=\"WOW!\")"
    }
  }
}

Another option would be to follow the javadoc style and do something like this:

"/pet":{  
  "post":{  
    "summary":"<b>@GreatOperation(yell=\"WOW!\")</b><br/>Add a new pet to the store",
    "description":"",
    "operationId":"addPet",
  }
}

But in this last option the documentation for @GreatOperation is lost. You could also use both options.

what do you think? For me, with such vendor extensions in place I would write a function in swagger-ui to show the annotations in a table or so.

EDIT: You mention it should be generally applicable. Of course this is more a generally applicable solution for custom documentation.

[sdaschner]

The later option is possible, the only problem I have with it is that it clutters the description summary pretty much. The original idea of the Analyzer was to provide a technology agnostic HTTP documentation that is easily generated from code. What benefit does the user have from reading @GreatOperation? What I could potentially see is something like inheriting just the JavaDoc from the @Documented annotation. So something like:

"/pet":{  
  "post":{  
    "summary":"Add a new pet to the store<br/>This is a great operation!",
    "description":"",
    "operationId":"addPet",
  }
}

Then the (generally applicable) approach would be: Take the JavaDoc, if there is any @Documented annotation annotated to the method, take this JavaDoc as well. WDYT?

However, in my eyes this is a rather minor improvement, so please don't mind if I lay the priorities to other features. But maybe you would like to fork & contribute? :-)