Spring auto JSONDoc scanner

[ntatsumi]

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]

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]

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]

Not to sound ungrateful, but nothing for @RepositoryRestResource ?

[bedge]

Not to sound ungrateful, but nothing for @RepositoryRestResource ?

[fabiomaffioletti]

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

[fabiomaffioletti]

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]

Please see my pull request: #128

[ntatsumi]

Please see my pull request: #128

[fabiomaffioletti]

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.

[fabiomaffioletti]

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]

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]

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]

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.

[fabiomaffioletti]

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]

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]

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]

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.

[fabiomaffioletti]

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]

Thanks!

[ntatsumi]

Thanks!