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

Spring auto JSONDoc scanner #127

Closed
ntatsumi opened this issue Jul 31, 2015 · 10 comments
Closed

Spring auto JSONDoc scanner #127

ntatsumi opened this issue Jul 31, 2015 · 10 comments
Milestone

Comments

@ntatsumi
Copy link

@ntatsumi ntatsumi commented Jul 31, 2015

I implemented SpringAutoJSONDocScanner that auto documents Spring controllers when JSONDoc annotations are absent. The scanner picks up unique controller classes in the order of @Api, @RestController, and @controller.

The interpreted Spring annotations are: @ResponseStatus, @RequestMapping, @PathVariable, @RequestParam, @requestbody, @ModelAttribute, and @PreAuthorize. Java method and field signatures are also used to help document. Unique objects that are used as parameters inside the detected endpoints are also documented automatically.

The groups are organized by the suffix of package name.

I think SpringAutoJSONDocScanner would benefit a lot of people. Let me know what you think! Thanks.

@crichey
Copy link

@crichey crichey commented Jul 31, 2015

Sounds great. Where do we get it?

Sent from my iPhone

On Jul 31, 2015, at 12:15, Noriaki Tatsumi notifications@github.com wrote:

I implemented SpringAutoJSONDocScanner that auto documents Spring controllers when JSONDoc annotations are absent. The scanner picks up unique controller classes in the order of @Api, @RestController, and @controller.

The interpreted Spring annotations are: @ResponseStatus, @RequestMapping, @PathVariable, @RequestParam, @requestbody, @ModelAttribute, and @PreAuthorize. Java method and field signatures are also used to help document. Unique objects that are used as parameters inside the detected endpoints are also documented automatically.

The groups are organized by the suffix of package name.

I think SpringAutoJSONDocScanner would benefit a lot of people. Let me know what you think! Thanks.


Reply to this email directly or view it on GitHub.

@bedge
Copy link

@bedge bedge commented Jul 31, 2015

Not to sound ungrateful, but nothing for @RepositoryRestResource ?

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Jul 31, 2015

Guys i am on holiday. I'll work on this as soon as I come back.
Il 31/lug/2015 18:34, "Bruce Edge" notifications@github.com ha scritto:

Not to sound ungrateful, but nothing for @RepositoryRestResource ?


Reply to this email directly or view it on GitHub
#127 (comment)
.

@ntatsumi
Copy link
Author

@ntatsumi ntatsumi commented Aug 2, 2015

Please see my pull request: #128

@fabiomaffioletti fabiomaffioletti modified the milestone: 1.1.17 Aug 5, 2015
@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Aug 5, 2015

I just pushed a big refactoring that fixes this issue (issue #111). It's in a branch named ISSUE-127 and in a few hours should be available as SNAPSHOT on maven. Version is 1.1.17-SNAPSHOT. You are encouraged to try it out and let me know your comments before I merge it to master and release it.

@ntatsumi
Copy link
Author

@ntatsumi ntatsumi commented Aug 6, 2015

Looks great.

Can you add scanning of @ModelAttribute? How about objects?

In my implementation, I also auto assigned the group with the suffix of package name. I would like that for my own use case but that might be too opinionated for the general audience?

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Aug 6, 2015

If I am not wrong @ModelAttribute is something that you should use in non-REST services, where you can put objects in the model to be accessible in the view, so I don't think it's something that is worth adding to the scan...

What do you mean with "How about objects?"

Having the package suffix as group is something that is worth discussing with other people as well, so please share your comments.

@ntatsumi
Copy link
Author

@ntatsumi ntatsumi commented Aug 6, 2015

I believe @RequestParam can be used for primitive wrappers and Strings only. @ModelAttribute enables you to use your POJOs.

I'd expect auto scan to also produce ApiObjectDoc that are used by the REST endpionts like I did here:
https://github.com/fabiomaffioletti/jsondoc/pull/128/files#diff-d256099629cd224023301e49c2edf7a0R173

You have to iterate through the array of verbs on line 221 in AbstractJSONDocScanner:
https://github.com/fabiomaffioletti/jsondoc/blob/ISSUE-127/jsondoc-core/src/main/java/org/jsondoc/core/scanner/AbstractJSONDocScanner.java#L221

@fabiomaffioletti
Copy link
Owner

@fabiomaffioletti fabiomaffioletti commented Aug 7, 2015

I enabled @ModelAttribute scan and fixed the third point. I did not work on the second point though, I think that for now it's overkill, but I prepared the ground for the future if it will be needed: see line 41 of AbstractSpringJSONDocScanner and, if you want, implement that method in the proper way. Please be aware that your previous implementation did not take into account some cases, for example something like byte[], List[], ResponseEntity, ResponseEntity<List>, and so on.

@ntatsumi
Copy link
Author

@ntatsumi ntatsumi commented Aug 8, 2015

Thanks!

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.