search

ScaCap / spring-auto-restdocs

Spring Auto REST Docs is an extension to Spring REST Docs
https://scacap.github.io/spring-auto-restdocs/
Apache License 2.0
311 stars 86 forks source link

REQ: Help with special cases #183

Closed wolverine2710 closed 6 years ago

wolverine2710 commented 6 years ago

Hi Florian,

For starters, I apologize for abusing the 'issues' but I haven't been able to find another way to contact you, went to your website etc. Feel free to remove this issue.

I've RTFM-ed, read your slides, watched your video presentation and Googled but couldn't find what I'm looking for.

We have used Spring Rest Docs (SRD) for the last 6 months. It works very nice but its gets time consuming. Especially when writing unit tests outside the happy path. As in testing the fault situations where one supplies the REST with missing parameters etc. With SRD each and every field has to be accounted for. Hence a lot of work getting all the fieldWithPath descriptors correct.

We are trying to switch from SRD to SARD. Currently I'm creating a POC and try to convert existing unit tests to SARD. There are a couple of things which give me a slight headache. So I've a few questions:

1) Is there a forum for SARD or a mailinglist or something like that. Haven't been able to find it.

2) Is it possible to exclude variables from being shown in the generated REST documentation for example with a POST. We have Hibernate domain objects which have an id field. When creating the id is shown in the JSON response and needed later for example with a PUT. With a POST an id is not allowed. With SARD however the id is shown in all cases. Is it possible to suppress it when issuing a POST?

3) We handle our JSON responses in a generic we and use a RESTResponse object for it. Code: return RestResponse.create(, HttpStatus.CREATED); RestResponse generates two JSON objects, meta{} and data{}. Meta contains the RestMetadata object. Its has a fixed number of fields AND SARD shows info for those field. The data object however changes all the time depending on what object we create and hence the fields in it. The only output we get from SARD is data (Path) Var (Type) false (optional) and a generic description. It is somehow possible to show the fields of . Thats essential for us.

4) I've noticed that when using @NotBlank on the getter of a field that in the description javax.validation.constraints.NotBlank is shown and the optional field shows true. I had expected like with @Notnull that optional is false and that some intuitive message in the descrption would be shown. Is this a bug or this by desgin? Iirc I've seen for one or two other validators as well but can't recall them atm.

I hope you are able to help me out and/or point me to some forum where I asks questions and learn from other.

PS. SARD which like magic and its very very usefull.

With kind regards, Jan

jmisur commented 6 years ago

Hi Jan, great that you're pushing for SARD even though not everything works for you guys.

  1. We created new Stackoverflow tag spring-auto-restdocs which you can use to post questions. However all your problems seem like missing features, so GitHub Issues is the proper place.
  2. When analyzing request/response classes we use Jackson serializer, that's why all fields are present. Issue for this is https://github.com/ScaCap/spring-auto-restdocs/issues/142. You can add your scenario (some code preferably) into it.
  3. Would you mind creating an issue with exact relevant code which doesn't work for you (POJOs, Resource). We have no idea how it actually looks like.
  4. Please create an issue for this, it might very well be that we're ignoring such annotations on getters.
wolverine2710 commented 6 years ago

Thanks for the response, its very much appreciated. I'm gonna create issue tickets for the points mentioned. Hopefully I can upload files as not to bloat the issue(s).

Wrt point (4) @notblank aka javax.validation.constraints.NotBlank it seems its covered by issue #174 "Support for Bean Validation 2.0 and Hibernate Validator 6.0". We are indeed using Hibernate Validator 6.0.4.

jmisur commented 6 years ago

Thanks for the tickets, I'll close this one.