Giter Club home page Giter Club logo

Comments (9)

wilkinsona avatar wilkinsona commented on August 11, 2024 1

Thanks for the suggestion. Are you aware of relaxedRequestFields()? I wonder how close it is to meeting your needs:

You can also document fields in a relaxed mode, where any undocumented fields do not cause a test failure. To do so, use the relaxedRequestFields and relaxedResponseFields methods on org.springframework.restdocs.payload.PayloadDocumentation. This can be useful when documenting a particular scenario where you want to focus only on a subset of the payload.

from spring-restdocs.

Kieun avatar Kieun commented on August 11, 2024

The main purpose of the feature request is not for testing but for documentation. Like any other fields in the snippets, it would be great to have optional properties so that the custom snippets might have a way to present such things.
Without such supports, we need to manually add that entire request body is optional or required.

Let say we have following controller:

    @PostMapping(path = "/foo")
    ServerResponse<Foo> foo(@Valid @RequestBody Foo foo) {
       ....
    }

In above example, the request body is required if it is not explicitly marked as false. And we don't have a way to get such properties from the spring-restdocs so that it need to be manually added in the document at this moment.

from spring-restdocs.

wilkinsona avatar wilkinsona commented on August 11, 2024

Thanks. I think I understand now.

How would REST Docs' behavior change when a whole request or response body is marked as optional? If, as you say, it's not for testing but for documentation, then it may be better written directly in your .adoc file. Typically, to be supported in REST Docs there has to be some difference that can be tested and documented.

from spring-restdocs.

Kieun avatar Kieun commented on August 11, 2024

then it may be better written directly in your .adoc file.

We could manually add description saying the request body is optional in the .adoc file, but it is prone to making mistakes.
Instead, the default value for optional of RequestFieldsSnippet is false and if it is okay to missing body, then it would great to have set optional as true and generated snippets has such optional properties for the entire request body or response body. Then, with such information, we could define custom template to generate the snippets.

from spring-restdocs.

wilkinsona avatar wilkinsona commented on August 11, 2024

Have you considered a small wrapper around PayloadDocumentation.fieldWithPath(String) that calls optional()? Something like this:

public static FieldDescriptor optionalFieldWithPath(String path) {
	FieldDescriptor descriptor = PayloadDocumentation.fieldWithPath(path);
	descriptor.optional();
	return descriptor;
}

Alternatively, you could wrap PayloadDocumentation.requestFields(FieldDescriptor...) instead:

public static RequestFieldsSnippet optionalRequestFields(FieldDescriptor... descriptors) {
	for (FieldDescriptor descriptor : descriptors) {
		descriptor.optional();
	}
	return PayloadDocumentation.requestFields(Arrays.asList(descriptors));
}

This assumes that a request or response that includes any number of fields is acceptable. If the body should either be completely empty or completely present, any approach that marks fields as optional will not help.

from spring-restdocs.

Kieun avatar Kieun commented on August 11, 2024

Interesting. The wrapper would be helpful to set optional or required for each field. But, I don't think it doesn't fit to the use case.

@PostMapping(path = "/foo")
ServerResponse<Foo> foo(@Valid @RequestBody(required = false) Foo foo) {
   ....
}

class Foo {
    @NotEmpty
    String field1;
    @NotEmpty
    String field2;
}

In this example, foo could be null (which means empty request body), but it it is not null, then filed1 and filed2 should be required.

With your suggestion, we could not handle theses situation.

from spring-restdocs.

wilkinsona avatar wilkinsona commented on August 11, 2024

Thanks for the clarification. That is the situation that I tried to describe above:

This assumes that a request or response that includes any number of fields is acceptable. If the body should either be completely empty or completely present, any approach that marks fields as optional will not help.

I don't think request fields is a good way to achieve your goal. How would you expect the table of fields that is generated to express this requirement?

Let's take a step back. Please describe, in as much detail as possible, what you'd like REST Docs to generate for you. We can then work from there and figure out how it could be implemented.

from spring-restdocs.

Kieun avatar Kieun commented on August 11, 2024

I agree with that it might not be good choice to add something in the requestFields.

This is something that I would like to present in the documentations. If the request body is required, I would like to mark Request Body section title with *.

== Foo API
This is foo API

|===
s|Method access
|POST /foo
s|Content type
|application/json
s|Required scopes
|`+service+`
|===

=== Request

==== Request Body*

[cols="20,10,30,40", options="header"]
|===
|Field|Type|Constraints|Description
|
    
field1
|`+String+`
|Must not be empty
|This is field1 description
|
    
field2
|`+String+`
|Must not be empty
|This is field2 description
|

from spring-restdocs.

wilkinsona avatar wilkinsona commented on August 11, 2024

I think that's something that you will have to handle yourself. REST Docs doesn't generate the Request Body title unless you're using Asciidoctor and the operation macro. I wouldn't want to add a feature that's specific to that particular usage style.

I think you could still implement something that's specific to your needs that helps to keep the documentation and the implementation in sync. For example, you could test that a request with no body is accepted and in that same test write something to disk indicating that it's optional. You could then include this in your .adoc file.

from spring-restdocs.

Related Issues (20)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.