spring-projects/spring-restdocs

Test-driven documentation for RESTful services

luvarqpp

@luvarqpp

when I use reference (i.e. <<_some_headline, Reference>>) in fieldWithPath.description, maven compilation of asciidoctor prints false info about possibly broken link: "asciidoctor: INFO: possible invalid reference". Can this be corrected by some setup?

when I use same reference in main document, no info is printed through.

James Howe

@OrangeDog

Is there a good way to track down the cause of this error? Everything looks like it's UTF8 already.

Failed to load AsciiDoc document - invalid byte sequence in UTF-8

Andy Wilkinson

@wilkinsona

@luvarqpp I haven't seen that before. It should be able to resolve a link from a field's description. Some of the samples do so and they do not log anything when Asciidoctor's generating the HTML.

luvarqpp

@luvarqpp

@wilkinsona links seems working, despite given info message in maven (in console during build). I will have a look at samples, if they also have such info mesage

luvarqpp

@luvarqpp

@wilkinsona it seems that given sample project cannot be build at this time. Missing snapshot dependency (org.springframework.restdocs:spring-restdocs-asciidoctor:jar:2.0.5.BUILD-SNAPSHOT) I will have a look at it

Andy Wilkinson

@wilkinsona

If you haven't built and installed the main project locally, you'll need to add a plugin repository to the pom:

<pluginRepositories>
    <pluginRepository>
        <id>spring-snapshots</id>
        <name>Spring snapshots</name>
        <url>https://repo.spring.io/libs-snapshot</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </pluginRepository>
</pluginRepositories>

luvarqpp

@luvarqpp

jop, I have pasted it right now into the pom :)

Andy Wilkinson

@wilkinsona

No link-related messages are logged during the HTML rendering:

[INFO] --- asciidoctor-maven-plugin:1.5.8:process-asciidoc (generate-docs) @ rest-notes-spring-data-rest ---
Downloading: https://repo.spring.io/libs-snapshot/org/springframework/restdocs/spring-restdocs-asciidoctor/2.0.5.BUILD-SNAPSHOT/maven-metadata.xml
Downloaded: https://repo.spring.io/libs-snapshot/org/springframework/restdocs/spring-restdocs-asciidoctor/2.0.5.BUILD-SNAPSHOT/maven-metadata.xml (2 KB at 1.6 KB/sec)
Downloading: https://repo.spring.io/libs-snapshot/org/springframework/restdocs/spring-restdocs-asciidoctor/2.0.5.BUILD-SNAPSHOT/spring-restdocs-asciidoctor-2.0.5.BUILD-20191218.174537-10.pom
Downloaded: https://repo.spring.io/libs-snapshot/org/springframework/restdocs/spring-restdocs-asciidoctor/2.0.5.BUILD-SNAPSHOT/spring-restdocs-asciidoctor-2.0.5.BUILD-20191218.174537-10.pom (6 KB at 15.2 KB/sec)
Downloading: https://repo.spring.io/libs-snapshot/org/springframework/restdocs/spring-restdocs-asciidoctor/2.0.5.BUILD-SNAPSHOT/spring-restdocs-asciidoctor-2.0.5.BUILD-20191218.174537-10.jar
Downloaded: https://repo.spring.io/libs-snapshot/org/springframework/restdocs/spring-restdocs-asciidoctor/2.0.5.BUILD-SNAPSHOT/spring-restdocs-asciidoctor-2.0.5.BUILD-20191218.174537-10.jar (11 KB at 29.3 KB/sec)
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 0 resource
[INFO] Rendered /Users/awilkinson/dev/spring-projects/spring-restdocs/samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc
[INFO] Rendered /Users/awilkinson/dev/spring-projects/spring-restdocs/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc
[INFO] 
[INFO] --- maven-resources-plugin:3.1.0:copy-resources (copy-resources) @ rest-notes-spring-data-rest ---

luvarqpp

@luvarqpp

I have also used latest parent pom release

seems fine...

[INFO] --- asciidoctor-maven-plugin:2.0.0-RC.1:process-asciidoc (default-cli) @ rest-notes-spring-data-rest ---
[INFO] Using 'UTF-8' encoding to copy filtered resources.
[INFO] Copying 0 resource
[INFO] Rendered /home/luvar/github/spring-restdocs/samples/rest-notes-spring-data-rest/src/main/asciidoc/api-guide.adoc
[INFO] Rendered /home/luvar/github/spring-restdocs/samples/rest-notes-spring-data-rest/src/main/asciidoc/getting-started-guide.adoc
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS

also link in generated html is working... thanks for pointing me to sample. I will have a look at my project and try to pinpoint difference

should I post pull request to updated things in pom (with added repository)?

Andy Wilkinson

@wilkinsona

Yes please. That sample should really have the <pluginRepository> in it by default.

luvarqpp

@luvarqpp

Links to other resources text have link to api-guide.html#resources-index-links, which is not working, through that is perhaps bug in documentation (referencing nonexistent thing)

on the other side, I have found, that sample project is using that thing in square brackets (labels?) and I am trying to use implicit label for headline

*label => explicit inline anchor

Andy Wilkinson

@wilkinsona

The links in the sample are a bug. It's a - versus _ thing.

The sample uses the same <<_some_headline, Reference>> syntax as you said above that you are using

luvarqpp

@luvarqpp

hmmm, I have seen in api-guide.doc something like [[overview-http-verbs]] \n == HTTP verbs

Andy Wilkinson

@wilkinsona

That's the section header, not the link

The links are done like this: https://github.com/spring-projects/spring-restdocs/blob/1ee96bbb7642614c59a67fccb0a7b8093a56d522/samples/rest-notes-spring-data-rest/src/test/java/com/example/notes/ApiDocumentation.java#L118

luvarqpp

@luvarqpp

I think, that it is explicit anchor and it is used in reference... I mean this feature: https://asciidoctor.org/docs/user-manual/#anchordef with linking to anchor. is it something different?

I got that feeling due this sample: https://asciidoctor.org/docs/user-manual/#validating-internal-cross-references

Andy Wilkinson

@wilkinsona

Sorry, you've lost me. What you've linked to shows [[anchor]] being used to define an anchor and <<anchor>> being used to link to it. That's exactly what the sample does

The validation of cross-references only happens when running in verbose/pedantic mode which is not the default. According to the documentation, they're also warnings messages rather than info so that doesn't seem to fit what you're seeing.

luvarqpp

@luvarqpp

so link <<resources-index-links>> is perhaps OK, but its target (anchor in [[style-like-this]]) has been removed meanwhile

ok, I have mixing two things at once. sorry.

sidenote, PR spring-projects/spring-restdocs#673

new question. if I have doc like this:

[[]some-section-custom-anchor]
== some section

lorem ipsum...

Andy Wilkinson

@wilkinsona

Thanks for the PR. Could you please update it to just add the snapshot plugin repository? The other changes aren't needed or aren't appropriate for 2.0.x.

luvarqpp

@luvarqpp

yes, of course

Andy Wilkinson

@wilkinsona

Thanks

luvarqpp

@luvarqpp

can I make links like this:

some section <<some-section-custom-anchor,here>> or linked also <<_some_section,here>>.

if I am not wrong, section title, gets autogenerated anchors prefixed by _ and all spaces replaced by _

it is autogenerated also in case when there is custom anchor defined?

PR changed

Andy Wilkinson

@wilkinsona

AFAIK, once you have defined an anchor for a section, Asciidoctor will not auto-generate one any more.

luvarqpp

@luvarqpp

I am trying it now, but it souds reasonable..

luvarqpp

@luvarqpp

sidenote: PR is still showing me something like " Changes requested \n 1 review requesting changes ", but I have resolved them all in single edit of commit... I see them both as resolved.

yes, defining custom anchor for section title, does cause that autogenerated anchor is not generated.

luvarqpp

@luvarqpp

Is there any "canonical" way, how to document associative endpoint? I.e., POST-ing "text/uri-list" content type and some url in body... Native approach leads me to PayloadHandlingException

Andy Wilkinson

@wilkinsona

REST Docs doesn't have any built-in support for documenting URI bodies, but the standard request body and HTTP request snippets shouldn't care what the request's content type is. What are you trying to use that's throwing the PayloadHandlingException?

luvarqpp

@luvarqpp

I have actually tried to document "asdf" attribute of payload... I see it now :) On the other side, can I add some description to whole body? Perhaps using title attribute... My original code was (webclient):

                .consumeWith(document("buplication/associateWithBook",
                        requestFields(
                                fieldWithPath("asdf").description("TODO add")
                        ),
                        responseFields(
                                PUBLICATION_FIELD_DESCRIPTORS
                        )
                ))

luvarqpp

@luvarqpp

My current code:

                .consumeWith(document("testCases/associateWithRelease",
                        requestFields(
                                attributes(key("title").value("single url to Release"))
                        ),
                        responseFields(
                                TESTCASE_FIELD_DESCRIPTORS
                        )
                ))

is still throwing exception... partial stacktrace:

org.springframework.restdocs.payload.PayloadHandlingException: Cannot handle text/uri-list content as it could not be parsed as JSON or XML

    at org.springframework.restdocs.payload.ContentHandler.forContentWithDescriptors(ContentHandler.java:69)
    at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:157)
    at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:78)
    at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:191)
    at org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.lambda$document$0(WebTestClientRestDocumentation.java:77)
    at org.springframework.test.web.reactive.server.DefaultWebTestClient$DefaultBodySpec.lambda$consumeWith$4(DefaultWebTestClient.java:437)
    at org.springframework.test.web.reactive.server.ExchangeResult.assertWithDiagnostics(ExchangeResult.java:206)
    at org.springframework.test.web.reactive.server.DefaultWebTestClient$DefaultBodySpec.consumeWith(DefaultWebTestClient.java:437)

I do not expect it. Is it due to use of requestFields(...)? Perhaps it does not make sense to generate any request-parameters.adoc, when I do not have ability to document its content... Do you have any suggestion? My goal is to have some sentence about request parameters (actually about whole request body) included in documentation in exactly same way, as I include snippet for json type request...

Andy Wilkinson

@wilkinsona

requestFields is intended for documenting a structured JSON or XML payload. In the absence of a Content-Type REST Docs will assume that it's JSON. I would use the existing HTTP request or request body snippets.

luvarqpp

@luvarqpp

@wilkinsona seems fair. I will use snippet of whole request and prepend some paragraph of text before it. It will not look (when just scrolling and looking for some pattern) same as documented json attributes (in table), but it seems as acceptable workaround. operation::someEndpoint/someUsecase[snippets='http-request']

Marcus Mosttler

@mmosttler_gitlab

I am trying to run a JUnit 5 test with RestDocs for a webflux app using WebTestClient using @WebFluxTest, @AutoConfigureRestDocs, @ExtendWith(RestDocumentation.class, SpringExtension.class) with WebTestClient autowired.

If I have 1 @Test with restdocs document calls it works fine, but when I add a 2nd rest docs test to show a different example of calling the service I get failures during the maven test phase.
For test #1:
java.lang.IllegalStateException: Context already exists. Did you forget to call afterTest()?
at org.springframework.restdocs.ManualRestDocumentation.beforeTest(ManualRestDocumentation.java:70)
at org.springframework.boot.test.autoconfigure.restdocs.RestDocsTestExecutionListener$DocumentationHandler.beforeTestMethod(RestDocsTestExecutionListener.java:66)
...

For test #2:
java.lang.NullPointerException
at org.springframework.restdocs.ManualRestDocumentation.beforeOperation(ManualRestDocumentation.java:85)
at org.springframework.restdocs.webtestclient.WebTestClientRestDocumentationConfigurer.createConfiguration(WebTestClientRestDocumentationConfigurer.java:73)
...

So I guess my question is 2 part. Is it possible to have more than 1 document tests in 1 test class for WebTestClient with WebFlux or does it have to be 1 to 1?
If you can have multiple, then what do I need to do to get the tests to pass consistently for RestDocs?

Andy Wilkinson

@wilkinsona

@mmosttler_gitlab Can you share a small sample project that reproduces the problem? I'm not totally sure that I've understood what's happening.

Where communities thrive

People

Repo info

Activity