Comments (9)
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
andrelaxedResponseFields
methods onorg.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.
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.
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.
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.
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.
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.
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.
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.
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)
- REST Docs RequestDocumentation questions when getting multipart/form-data bindings with `@ModelAttribute` (boot 3.1.1) HOT 2
- How to add third attribute column. Tried in many ways but it's not working? Pls help me. HOT 2
- How to get response body while generating the rest docs? HOT 1
- WebTestClient: Add AutoConfiguration for MockMvcWebTestClient? HOT 2
- Rest Assured approach. Test case got successfully passed but not getting the request.adoc, response.adoc file inside target folder. HOT 1
- Add ability to post-process operations HOT 7
- Upgrade to Spring Java Format 0.0.39
- Upgrade to Spring Java Format 0.0.39
- Upgrade to Spring Framework 6.0.14
- Perform compatibility testing against Framework 6.1
- UnsupportedOperationException when modifying request and response headers with Framework 6.0.9 and later
- Avoid substring creation when writing a portion of a string to a StringBuilder
- How to hide Request Body and curl particular fields like "Token"? while generating spring rest docs through rest assured approach HOT 1
- Request-body.adoc is coming as blank in case of get call HOT 3
- Except body fields how can I add others mandate fields like headers(correlationId, destination, srDate) HOT 1
- Getting issue related to query parameter. HOT 5
- Latest dependencies issue is coming while generating rest docs HOT 2
- Any concern that the underlying asciidoc gradle plugin doesn't work with Java 17 or 21? HOT 1
- Upgrade Gradle Enterprise Plugins
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
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.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from spring-restdocs.