Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Add support for documenting body of a request, response or request part

Browse Source 
Closes gh-318
Closes gh-319
This commit is contained in:
Andy Wilkinson
2016-10-31 12:46:36 +00:00
parent 1393182182
commit dec3727da1
31 changed files with 1160 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
spring-restdocs-core/src/test/java/org/springframework/restdocs/AbstractSnippetTests.java
View File

@@ -68,7 +68,11 @@ public abstract class AbstractSnippetTests {
}
public CodeBlockMatcher<?> codeBlock(String language) {
return SnippetMatchers.codeBlock(this.templateFormat, language);
return this.codeBlock(language, null);
}
public CodeBlockMatcher<?> codeBlock(String language, String options) {
return SnippetMatchers.codeBlock(this.templateFormat, language, options);
}
public TableMatcher<?> tableWithHeader(String... headers) {

10
spring-restdocs-core/src/test/java/org/springframework/restdocs/config/RestDocumentationConfigurerTests.java
View File

@@ -31,6 +31,8 @@ import org.springframework.restdocs.cli.HttpieRequestSnippet;
import org.springframework.restdocs.generate.RestDocumentationGenerator;
import org.springframework.restdocs.http.HttpRequestSnippet;
import org.springframework.restdocs.http.HttpResponseSnippet;
import org.springframework.restdocs.payload.RequestBodySnippet;
import org.springframework.restdocs.payload.ResponseBodySnippet;
import org.springframework.restdocs.snippet.Snippet;
import org.springframework.restdocs.snippet.StandardWriterResolver;
import org.springframework.restdocs.snippet.WriterResolver;
@@ -76,7 +78,9 @@ public class RestDocumentationConfigurerTests {
contains(instanceOf(CurlRequestSnippet.class),
instanceOf(HttpieRequestSnippet.class),
instanceOf(HttpRequestSnippet.class),
instanceOf(HttpResponseSnippet.class)));
instanceOf(HttpResponseSnippet.class),
instanceOf(RequestBodySnippet.class),
instanceOf(ResponseBodySnippet.class)));
assertThat(configuration, hasEntry(equalTo(SnippetConfiguration.class.getName()),
instanceOf(SnippetConfiguration.class)));
SnippetConfiguration snippetConfiguration = (SnippetConfiguration) configuration
@@ -138,7 +142,9 @@ public class RestDocumentationConfigurerTests {
contains(instanceOf(CurlRequestSnippet.class),
instanceOf(HttpieRequestSnippet.class),
instanceOf(HttpRequestSnippet.class),
instanceOf(HttpResponseSnippet.class), equalTo(snippet)));
instanceOf(HttpResponseSnippet.class),
instanceOf(RequestBodySnippet.class),
instanceOf(ResponseBodySnippet.class), equalTo(snippet)));
}
@Test

95
spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/RequestBodyPartSnippetTests.java Normal file
View File

@@ -0,0 +1,95 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.payload;
import java.io.IOException;
import org.junit.Test;
import org.springframework.restdocs.AbstractSnippetTests;
import org.springframework.restdocs.templates.TemplateEngine;
import org.springframework.restdocs.templates.TemplateFormat;
import org.springframework.restdocs.templates.TemplateResourceResolver;
import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.mock;
import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestPartBody;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
/**
* Tests for {@link RequestPartBodySnippet}.
*
* @author Andy Wilkinson
*/
public class RequestBodyPartSnippetTests extends AbstractSnippetTests {
public RequestBodyPartSnippetTests(String name, TemplateFormat templateFormat) {
super(name, templateFormat);
}
@Test
public void requestPartWithBody() throws IOException {
this.snippets.expect("request-part-one-body")
.withContents(codeBlock(null, "nowrap").content("some content"));
requestPartBody("one").document(this.operationBuilder.request("http://localhost")
.part("one", "some content".getBytes()).build());
}
@Test
public void requestPartWithNoBody() throws IOException {
this.snippets.expect("request-part-one-body")
.withContents(codeBlock(null, "nowrap").content(""));
requestPartBody("one").document(this.operationBuilder.request("http://localhost")
.part("one", new byte[0]).build());
}
@Test
public void subsectionOfRequestPartBody() throws IOException {
this.snippets.expect("request-part-one-body-beneath-a.b")
.withContents(codeBlock(null, "nowrap").content("{\"c\":5}"));
requestPartBody("one", beneathPath("a.b"))
.document(this.operationBuilder.request("http://localhost")
.part("one", "{\"a\":{\"b\":{\"c\":5}}}".getBytes()).build());
}
@Test
public void customSnippetAttributes() throws IOException {
this.snippets.expect("request-part-one-body")
.withContents(codeBlock("json", "nowrap").content("{\"a\":\"alpha\"}"));
TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
given(resolver.resolveTemplateResource("request-part-body"))
.willReturn(snippetResource("request-part-body-with-language"));
requestPartBody("one",
attributes(
key("language").value("json")))
.document(
this.operationBuilder
.attribute(TemplateEngine.class.getName(),
new MustacheTemplateEngine(
resolver))
.request("http://localhost")
.part("one",
"{\"a\":\"alpha\"}".getBytes())
.build());
}
}

92
spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/RequestBodySnippetTests.java Normal file
View File

@@ -0,0 +1,92 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.payload;
import java.io.IOException;
import org.junit.Test;
import org.springframework.restdocs.AbstractSnippetTests;
import org.springframework.restdocs.templates.TemplateEngine;
import org.springframework.restdocs.templates.TemplateFormat;
import org.springframework.restdocs.templates.TemplateResourceResolver;
import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.mock;
import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestBody;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
/**
* Tests for {@link RequestBodySnippet}.
*
* @author Andy Wilkinson
*/
public class RequestBodySnippetTests extends AbstractSnippetTests {
public RequestBodySnippetTests(String name, TemplateFormat templateFormat) {
super(name, templateFormat);
}
@Test
public void requestWithBody() throws IOException {
this.snippets.expect("request-body")
.withContents(codeBlock(null, "nowrap").content("some content"));
requestBody().document(this.operationBuilder.request("http://localhost")
.content("some content").build());
}
@Test
public void requestWithNoBody() throws IOException {
this.snippets.expect("request-body")
.withContents(codeBlock(null, "nowrap").content(""));
requestBody().document(this.operationBuilder.request("http://localhost").build());
}
@Test
public void subsectionOfRequestBody() throws IOException {
this.snippets.expect("request-body-beneath-a.b")
.withContents(codeBlock(null, "nowrap").content("{\"c\":5}"));
requestBody(beneathPath("a.b"))
.document(this.operationBuilder.request("http://localhost")
.content("{\"a\":{\"b\":{\"c\":5}}}").build());
}
@Test
public void customSnippetAttributes() throws IOException {
this.snippets.expect("request-body")
.withContents(codeBlock("json", "nowrap").content("{\"a\":\"alpha\"}"));
TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
given(resolver.resolveTemplateResource("request-body"))
.willReturn(snippetResource("request-body-with-language"));
requestBody(
attributes(
key("language").value("json")))
.document(
this.operationBuilder
.attribute(TemplateEngine.class.getName(),
new MustacheTemplateEngine(
resolver))
.request("http://localhost")
.content("{\"a\":\"alpha\"}").build());
}
}

92
spring-restdocs-core/src/test/java/org/springframework/restdocs/payload/ResponseBodySnippetTests.java Normal file
View File

@@ -0,0 +1,92 @@
/*
* Copyright 2014-2016 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.restdocs.payload;
import java.io.IOException;
import org.junit.Test;
import org.springframework.restdocs.AbstractSnippetTests;
import org.springframework.restdocs.templates.TemplateEngine;
import org.springframework.restdocs.templates.TemplateFormat;
import org.springframework.restdocs.templates.TemplateResourceResolver;
import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine;
import static org.mockito.BDDMockito.given;
import static org.mockito.Mockito.mock;
import static org.springframework.restdocs.payload.PayloadDocumentation.beneathPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseBody;
import static org.springframework.restdocs.snippet.Attributes.attributes;
import static org.springframework.restdocs.snippet.Attributes.key;
/**
* Tests for {@link ResponseBodySnippet}.
*
* @author Andy Wilkinson
*/
public class ResponseBodySnippetTests extends AbstractSnippetTests {
public ResponseBodySnippetTests(String name, TemplateFormat templateFormat) {
super(name, templateFormat);
}
@Test
public void responseWithBody() throws IOException {
this.snippets.expect("response-body")
.withContents(codeBlock(null, "nowrap").content("some content"));
PayloadDocumentation.responseBody().document(
this.operationBuilder.response().content("some content").build());
}
@Test
public void responseWithNoBody() throws IOException {
this.snippets.expect("response-body")
.withContents(codeBlock(null, "nowrap").content(""));
PayloadDocumentation.responseBody()
.document(this.operationBuilder.response().build());
}
@Test
public void subsectionOfResponseBody() throws IOException {
this.snippets.expect("response-body-beneath-a.b")
.withContents(codeBlock(null, "nowrap").content("{\"c\":5}"));
responseBody(beneathPath("a.b")).document(this.operationBuilder.response()
.content("{\"a\":{\"b\":{\"c\":5}}}").build());
}
@Test
public void customSnippetAttributes() throws IOException {
this.snippets.expect("response-body")
.withContents(codeBlock("json", "nowrap").content("{\"a\":\"alpha\"}"));
TemplateResourceResolver resolver = mock(TemplateResourceResolver.class);
given(resolver.resolveTemplateResource("response-body"))
.willReturn(snippetResource("response-body-with-language"));
responseBody(
attributes(
key("language").value("json")))
.document(
this.operationBuilder
.attribute(TemplateEngine.class.getName(),
new MustacheTemplateEngine(
resolver))
.response().content("{\"a\":\"alpha\"}")
.build());
}
}

13
spring-restdocs-core/src/test/java/org/springframework/restdocs/test/SnippetMatchers.java
View File

@@ -95,6 +95,15 @@ public final class SnippetMatchers {
return new MarkdownCodeBlockMatcher(language);
}
@SuppressWarnings({ "rawtypes" })
public static CodeBlockMatcher<?> codeBlock(TemplateFormat format, String language,
String options) {
if ("adoc".equals(format.getFileExtension())) {
return new AsciidoctorCodeBlockMatcher(language, options);
}
return new MarkdownCodeBlockMatcher(language);
}
private static abstract class AbstractSnippetContentMatcher
extends BaseMatcher<String> {
@@ -186,7 +195,7 @@ public final class SnippetMatchers {
protected AsciidoctorCodeBlockMatcher(String language, String options) {
super(TemplateFormats.asciidoctor());
this.addLine("[source," + language
this.addLine("[source" + (language == null ? "" : "," + language)
+ (options == null ? "" : ",options=\"" + options + "\"") + "]");
this.addLine("----");
this.addLine("----");
@@ -204,7 +213,7 @@ public final class SnippetMatchers {
protected MarkdownCodeBlockMatcher(String language) {
super(TemplateFormats.markdown());
this.addLine("```" + language);
this.addLine("```" + (language == null ? "" : language));
this.addLine("```");
}

4
spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-body-with-language.snippet Normal file
View File

@@ -0,0 +1,4 @@
[source,{{language}},options="nowrap"]
----
{{body}}
----

4
spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/request-part-body-with-language.snippet Normal file
View File

@@ -0,0 +1,4 @@
[source,{{language}},options="nowrap"]
----
{{body}}
----

4
spring-restdocs-core/src/test/resources/custom-snippet-templates/asciidoctor/response-body-with-language.snippet Normal file
View File

@@ -0,0 +1,4 @@
[source,{{language}},options="nowrap"]
----
{{body}}
----

3
spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-body-with-language.snippet Normal file
View File

@@ -0,0 +1,3 @@
```{{language}}
{{body}}
```

3
spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/request-part-body-with-language.snippet Normal file
View File

@@ -0,0 +1,3 @@
```{{language}}
{{body}}
```

3
spring-restdocs-core/src/test/resources/custom-snippet-templates/markdown/response-body-with-language.snippet Normal file
View File

@@ -0,0 +1,3 @@
```{{language}}
{{body}}
```