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

Closed
volyx opened this issue May 15, 2015 · 5 comments
Closed
Assignees
Labels
Milestone

Comments

@volyx
Copy link

@volyx volyx commented May 15, 2015

Can jsondoc understand spring annotation?
77fd0631b8bada7177a108b35af8cfb7 1

If it can, i remove @ApiBodyObject annotation.

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti 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
Copy link

@bedge 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
Copy link
Author

@volyx 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
Copy link
Owner

@fabiomaffioletti 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
Copy link

@rajiv-shringi-A1 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
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants
You can’t perform that action at this time.