Skip to content
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

volyx opened this issue May 15, 2015 · 5 comments


Copy link

volyx commented May 15, 2015

Can jsondoc understand spring annotation?
77fd0631b8bada7177a108b35af8cfb7 1

If it can, i remove @ApiBodyObject annotation.

Copy link

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.

Copy link

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.

Copy link

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 as completed May 16, 2015
@volyx volyx reopened this May 16, 2015
Copy link

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.

Copy link

+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
None yet

No branches or pull requests

4 participants