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

Comments

Projects
None yet
4 participants
@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

This comment has been minimized.

Show comment
Hide comment
@crichey

crichey 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.

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

This comment has been minimized.

Show comment
Hide comment
@bedge

bedge Jul 31, 2015

Not to sound ungrateful, but nothing for @RepositoryRestResource ?

bedge commented Jul 31, 2015

Not to sound ungrateful, but nothing for @RepositoryRestResource ?

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Jul 31, 2015

Owner

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)
.

Owner

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

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi Aug 2, 2015

Please see my pull request: #128

ntatsumi commented Aug 2, 2015

Please see my pull request: #128

@fabiomaffioletti fabiomaffioletti modified the milestone: 1.1.17 Aug 5, 2015

@fabiomaffioletti

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 5, 2015

Owner

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.

Owner

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

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi 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?

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

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 6, 2015

Owner

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.

Owner

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

This comment has been minimized.

Show comment
Hide comment
@ntatsumi

ntatsumi 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

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

This comment has been minimized.

Show comment
Hide comment
@fabiomaffioletti

fabiomaffioletti Aug 7, 2015

Owner

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.

Owner

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

This comment has been minimized.

Show comment
Hide comment
@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