New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Can jsondoc understand spring annotation, like @RequestBody and @PathVariable? #111

Closed
volyx opened this Issue May 15, 2015 · 5 comments

Comments

Projects
None yet
4 participants
@volyx

volyx commented May 15, 2015

Can jsondoc understand spring annotation?
77fd0631b8bada7177a108b35af8cfb7 1

If it can, i remove @ApiBodyObject annotation.

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti May 15, 2015

Owner

It does can understand spring's annotations, but it's has an "opt-it" strategy, meaning that you still need to put jsondoc annotations to decide what you would like to document and what not.

Owner

fabiomaffioletti commented May 15, 2015

It does can understand spring's annotations, but it's has an "opt-it" strategy, meaning that you still need to put jsondoc annotations to decide what you would like to document and what not.

@bedge

This comment has been minimized.

Show comment
Hide comment
@bedge

bedge May 15, 2015

Would it be possible to have a more global flag to eliminate the need to explicitly add annotations for everything? Maybe a file or package scope flag?
Would save on a lot of annotation typing.

bedge commented May 15, 2015

Would it be possible to have a more global flag to eliminate the need to explicitly add annotations for everything? Maybe a file or package scope flag?
Would save on a lot of annotation typing.

@volyx

This comment has been minimized.

Show comment
Hide comment
@volyx

volyx May 16, 2015

Yes, it will be good.
I interested in such case:
If I mark method with annotation @ApiMethod i mean that this method will be available in jsondoc with all parameters. Maybe we can define any flag only for jsondoc-springmvc module?
It will be good especially for small projects.

volyx commented May 16, 2015

Yes, it will be good.
I interested in such case:
If I mark method with annotation @ApiMethod i mean that this method will be available in jsondoc with all parameters. Maybe we can define any flag only for jsondoc-springmvc module?
It will be good especially for small projects.

@volyx volyx closed this May 16, 2015

@volyx volyx reopened this May 16, 2015

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti May 18, 2015

Owner

The good thing about jsondoc is that it is framework agnostic, meaning that you can put its annotation on anything you want (you can even annotate non-controller and non-dto classes and have the doc and playground generated and working properly). To do that I needed to require the "technical writer" to decide what to document, this is the reason behind the "annotate everything" approach. But you are right, @ApiMethod would be enough, in case you are for example annotating a spring controller. Changing that in this moment would mean a lot of work though, which I cannot afford right now.

Owner

fabiomaffioletti commented May 18, 2015

The good thing about jsondoc is that it is framework agnostic, meaning that you can put its annotation on anything you want (you can even annotate non-controller and non-dto classes and have the doc and playground generated and working properly). To do that I needed to require the "technical writer" to decide what to document, this is the reason behind the "annotate everything" approach. But you are right, @ApiMethod would be enough, in case you are for example annotating a spring controller. Changing that in this moment would mean a lot of work though, which I cannot afford right now.

@rajiv-shringi-A1

This comment has been minimized.

Show comment
Hide comment
@rajiv-shringi-A1

rajiv-shringi-A1 Jun 18, 2015

+1 for this enhancement. The opt-in approach can be controlled by a package level global flag (example: if the flag is true for a given package, then you have to opt in and explicitly annotate in order to generate documentation for the controllers in that package). But that should be only for annotations @Api and/or @ApiMethod. I believe the @ApiPathParam, @ApiRequestBody annotations are redundant. The @PathVariable and @requestbody annotations should be enough for generating playground.

rajiv-shringi-A1 commented Jun 18, 2015

+1 for this enhancement. The opt-in approach can be controlled by a package level global flag (example: if the flag is true for a given package, then you have to opt in and explicitly annotate in order to generate documentation for the controllers in that package). But that should be only for annotations @Api and/or @ApiMethod. I believe the @ApiPathParam, @ApiRequestBody annotations are redundant. The @PathVariable and @requestbody annotations should be enough for generating playground.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment