Previously, when a field was documented it would implicitly document
the whole subsection of the payload identified by that field. This
could lead to users inadvertently failing to document part of the
payload. Arguably, this was a bug as it violated REST Docs' principle
of producing accurate, detail documentation. However, fixing it
requires a breaking change as people may also be relying on this
behaviour. A balance needed to be struck so the fix is being made in
a minor release.
This commit introduces a new subsectionWithPath method which returns a
SubsectionDescriptor; a specialisation of FieldDescriptor. Users
that were intentionally relying on the old behaviour will have to
replace some usage of fieldWithPath with subsectionWithPath instead.
Users who were unintentionally relying on the old behaviour will have
to add some additional descriptors produced using fieldWithPath and
will receive more accurate documentation in return.
Closes gh-274
- Rebase on latest code, and make use of new support for the same
TemplatedSnippet producing multiple snippets with different names
from the same template
- Expand the documentation
- Apply code formatting
- Add support for relaxed documentation of a request part's fields
Closes gh-270
Previously a TemplatedSnippet could only write snippets with the
same name as its template. This meant that the same template could
not be used to produce multiple snippets with different names.
This commit separates the snippet name from the template name, thereby
allowing the snippet name to vary while the template name remains the
same. For backwards compatibility, the default behaviour is for the
template name and snippet name to remain the same. The new overloaded
constructor can be used when the names need to differ.
Closes gh-320
Rather than introducing a custom macro, this commit opts to implicitly
configure the snippets attribute instead. The attribute is configured
will the path into which snippets are generated, relative to the
directory that contains the Asciidoctor document that is being
rendered.
The samples and documentation have been updated to use the new
spring-restdocs-asciidoctor module and the implicitly configured
snippets attribute.
Closes gh-297
Rather than requiring an output directory to be explcitly configured,
a default is now automatically configured based on the build tool
that's being used. When using Gradle, snippets will be generated in
build/generated-snippets. When using Maven, snippets will be
generated in target/generated-snippets.
See gh-297
Previously, the logic that determined the field’s type would incorrectly
look at the contents of the array. For example, if the array contained
one or more objects, the field’s type would be resolved as Object rather
than Array.
This commit updates JsonFieldPath to record when a path explicitly
identifies an array so that the array itself is used to determine the
field’s type rather than its contents.
Closes gh-292
QueryStringParser has been moved into the operation page. In the
unlikely event that there were any external users of the class, a
deprecated version remains in the cli package for backwards
compatibility. It will be removed in 1.2.
Closes gh-286
Missing optional fields require a type to be explicitly provided as
it cannot be inferred from the payload. Ignored fields are not
included in the documentation, yet, previously, a field that was
missing, optional, and ignored would still require a type to be
provided otherwise the test would fail. This was pointless as the
field wasn't going to appear in the documentation.
This commit updates the fields snippets so that a type is no longer
required for a field that is missing, optional and ignored.
Closes gh-289
Previously, spring-restdocs-core had a dependency on spring-webmvc
however it only used classes from spring-web. This commit moves
the spring-webmvc dependency from spring-restdocs-core to
spring-restdocs-mockmvc where it's needed. It's now in the runtime
scope (rather than compile) as it's not needed at compile time but
is needed at runtime by the MockMvc support in spring-test.
Closes gh-273
Previously, if a MockMvc request was made with parameters and body
content, the parameters were omitted from the resulting curl, HTTPie
and HTTP request snippets.
This commit updates the affected snippets to ensure that the
parameters are included. The user-provided content is interpreted
as indicating that the parameters should be sent in the query string
rather than as form-encoded content.
Closes gh-239
Previously, the curl and HTTPie request snippets always excluded the
Host header, relying on the Host header that’s auto-generated by curl
and HTTPie instead. This worked well for the most part, but meant that
incorrect snippets were generated when the request was being sent with
a custom host header that did not match the header that would be
auto-generated.
This commit updates CliOperationRequest to only filter out the Host
header if it’s the same as the header that would be auto-generated
by curl or HTTPie.
Closes gh-258
Previously, OperationRequestFactory would add a Host header if one did
not already exist in the request’s headers, however it did not include
the port. This meant that when the request was being made to a
non-standard port (a port other than 80 for an HTTP request and 443 for
an HTTPS request) the Host header was incorrect.
This commit updates OperationRequestFactory to check the URI for a port
and, if it has one, include it in the Host header.
UriModifyingOperationPreprocessor has also been updated to correctly
include the port in the Host header.
Closes gh-269
Previously, if alwaysDo was used and the user wanted to generate
one or more additional snippets when calling perform a separate call
to `snippets` was made prior to calling `perform`. This had two
problems:
- it required the result handler to be stateful (see gh-243)
- it wasn't clear that the additional snippets would be produced when
a subsequent call to perform was made
This commit introduces a new API that allows the additional snippets
to be specified within the MockMvc call. The old API has been
deprecated and will be removed in 2.0.
Closes gh-249
applyPathPrefix is generally useful but, previously, it was only
available as a protected method on AbstractFieldsSnippet.
This commit moves the method from AbstractFieldsSnippet to
PayloadDocumentation where it's now public and static.
Closes gh-245
