Very long notes in @ApiOperation annotation -> outsource it?

[Fabian Mielke]

Hello Swagger Community,

I am facing a problem that refers to the @ApiOperation annotation. The swagger core tells us to use the notes for example requests and responses:

The notes allows you to give significantly more details about the operations (e.g. you can include request samples and responses here). swagger core on github

I think it's not good for readable code. I have to write many stuff in the notes, for example special dependencies, behaviour of the resource and like swagger said: body exaamples, and not only in JSON... A java REST resource where the most of the java code are "notes"? Not very nice...

So, annotations have to be static. Has someone an idea to outsource the notes of the annotation?

Thank you very much!

Kind regards, Fabian

[tony tam]

Hi, I suggest two approaches.

First, using references to static final String values should be fine, you can then reference centralized, external files.

Next, you can intercept the Swagger object on response, and inject whatever you like in there.  That will allow you to be dynamic with the descriptions and make them load from property files, etc.

For the 2nd option, please take a look here for an example:

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-generator/src/main/java/io/swagger/generator/DynamicSwaggerConfig.java

[Fabian Mielke]

Hello Tony,

thanks for your reply.

I should say that we only use the swagger-ui module, because we generate API explorers für moduralized JAX-RS and Spring APIs. Does option 2 work for "swagger-ui only" usecases, too?

Kind regards,

Fabian

[tony tam]

If you are producing a swagger pojo from some other mechanism then if you can get access to it, you can easily mutate it.