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

Add support for configuring default request and response preprocessors

Browse Source 
See gh-424
This commit is contained in:
Filip Hrisafov
2017-09-02 10:35:11 +02:00
committed by Andy Wilkinson
parent 22cf08a9ad
commit 4f8b173836
20 changed files with 699 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
spring-restdocs-core/src/main/java/org/springframework/restdocs/config/OperationPreprocessorsConfigurer.java Normal file
View File

@@ -0,0 +1,82 @@
/*
* Copyright 2014-2017 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.config;
import java.util.Map;
import org.springframework.restdocs.RestDocumentationContext;
import org.springframework.restdocs.generate.RestDocumentationGenerator;
import org.springframework.restdocs.operation.preprocess.OperationPreprocessor;
import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
import org.springframework.restdocs.operation.preprocess.Preprocessors;
/**
* A configurer that can be used to configure the default operation preprocessors that need to be used.
*
* @param <PARENT> The type of the configurer's parent
* @param <TYPE> The concrete type of the configurer to be returned from chained methods
* @author Filip Hrisafov
* @since 2.0.0
*/
public abstract class OperationPreprocessorsConfigurer<PARENT, TYPE>
extends AbstractNestedConfigurer<PARENT> {
private OperationRequestPreprocessor defaultOperationRequestPreprocessor;
private OperationResponsePreprocessor defaultOperationResponsePreprocessor;
/**
* Creates a new {@code OperationPreprocessorConfigurer} with the given {@code parent}.
*
* @param parent the parent
*/
protected OperationPreprocessorsConfigurer(PARENT parent) {
super(parent);
}
@Override
public void apply(Map<String, Object> configuration, RestDocumentationContext context) {
configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR,
this.defaultOperationRequestPreprocessor);
configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR,
this.defaultOperationResponsePreprocessor);
}
/**
* Configures the default documentation operation request preprocessors.
*
* @param preprocessors the preprocessors
* @return {@code this}
*/
@SuppressWarnings("unchecked")
public TYPE withDefaultRequestPreprocessors(OperationPreprocessor... preprocessors) {
this.defaultOperationRequestPreprocessor = Preprocessors.preprocessRequest(preprocessors);
return (TYPE) this;
}
/**
* Configures the default documentation operation response preprocessors.
*
* @param preprocessors the preprocessors
* @return {@code this}
*/
@SuppressWarnings("unchecked")
public TYPE withDefaultResponsePreprocessors(OperationPreprocessor... preprocessors) {
this.defaultOperationResponsePreprocessor = Preprocessors.preprocessResponse(preprocessors);
return (TYPE) this;
}
}

13
spring-restdocs-core/src/main/java/org/springframework/restdocs/config/RestDocumentationConfigurer.java
View File

@@ -36,12 +36,14 @@ import org.springframework.restdocs.templates.mustache.MustacheTemplateEngine;
* Abstract base class for the configuration of Spring REST Docs.
*
* @param <S> The concrete type of the {@link SnippetConfigurer}.
* @param <P> The concrete type of the {@link OperationPreprocessorsConfigurer}
* @param <T> The concrete type of this configurer, to be returned from methods that
* support chaining
* @author Andy Wilkinson
* @author Filip Hrisafov
* @since 1.1.0
*/
public abstract class RestDocumentationConfigurer<S extends AbstractConfigurer, T> {
public abstract class RestDocumentationConfigurer<S extends AbstractConfigurer, P extends AbstractConfigurer, T> {
private final WriterResolverConfigurer writerResolverConfigurer = new WriterResolverConfigurer();
@@ -55,6 +57,14 @@ public abstract class RestDocumentationConfigurer<S extends AbstractConfigurer,
*/
public abstract S snippets();
/**
* Returns an {@link OperationPreprocessorsConfigurer} that can be used to configure the operation request and
* response preprocessors that will be used during the documentation.
*
* @return the operation preprocessors configurer
*/
public abstract P operationPreprocessors();
/**
* Configures the {@link TemplateEngine} that will be used for snippet rendering.
*
@@ -90,6 +100,7 @@ public abstract class RestDocumentationConfigurer<S extends AbstractConfigurer,
protected final void apply(Map<String, Object> configuration,
RestDocumentationContext context) {
List<AbstractConfigurer> configurers = Arrays.asList(snippets(),
operationPreprocessors(),
this.templateEngineConfigurer, this.writerResolverConfigurer);
for (AbstractConfigurer configurer : configurers) {
configurer.apply(configuration, context);

61
spring-restdocs-core/src/main/java/org/springframework/restdocs/generate/RestDocumentationGenerator.java
View File

@@ -41,6 +41,7 @@ import org.springframework.util.Assert;
* @param <REQ> the request type that can be handled
* @param <RESP> the response type that can be handled
* @author Andy Wilkinson
* @author Filip Hrisafov
* @since 1.1.0
*/
public final class RestDocumentationGenerator<REQ, RESP> {
@@ -55,6 +56,19 @@ public final class RestDocumentationGenerator<REQ, RESP> {
*/
public static final String ATTRIBUTE_NAME_DEFAULT_SNIPPETS = "org.springframework.restdocs.defaultSnippets";
/**
* Name of the operation attribute used to hold the default operation request preprocessor.
*/
public static final String ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR =
"org.springframework.restdocs.defaultOperationRequestPreprocessor";
/**
* Name of the operation attribute used to hold the default operation response preprocessor.
*/
public static final String ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR =
"org.springframework.restdocs.defaultOperationResponsePreprocessor";
private final String identifier;
private final OperationRequestPreprocessor requestPreprocessor;
@@ -183,12 +197,9 @@ public final class RestDocumentationGenerator<REQ, RESP> {
* @throws RestDocumentationGenerationException if a failure occurs during handling
*/
public void handle(REQ request, RESP response, Map<String, Object> configuration) {
OperationRequest operationRequest = this.requestPreprocessor
.preprocess(this.requestConverter.convert(request));
OperationResponse operationResponse = this.responsePreprocessor
.preprocess(this.responseConverter.convert(response));
Map<String, Object> attributes = new HashMap<>(configuration);
OperationRequest operationRequest = preprocessRequest(request, attributes);
OperationResponse operationResponse = preprocessResponse(response, attributes);
Operation operation = new StandardOperation(this.identifier, operationRequest,
operationResponse, attributes);
try {
@@ -228,6 +239,46 @@ public final class RestDocumentationGenerator<REQ, RESP> {
return combinedSnippets;
}
private OperationRequest preprocessRequest(REQ request, Map<String, Object> configuration) {
List<OperationRequestPreprocessor> requestPreprocessors = getRequestPreprocessors(configuration);
OperationRequest operationRequest = this.requestConverter.convert(request);
for (OperationRequestPreprocessor preprocessor : requestPreprocessors) {
operationRequest = preprocessor.preprocess(operationRequest);
}
return operationRequest;
}
private List<OperationRequestPreprocessor> getRequestPreprocessors(Map<String, Object> configuration) {
List<OperationRequestPreprocessor> preprocessors = new ArrayList<>(2);
preprocessors.add(this.requestPreprocessor);
OperationRequestPreprocessor defaultRequestPreprocessor = (OperationRequestPreprocessor) configuration.get(
RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR);
if (defaultRequestPreprocessor != null) {
preprocessors.add(defaultRequestPreprocessor);
}
return preprocessors;
}
private OperationResponse preprocessResponse(RESP response, Map<String, Object> configuration) {
List<OperationResponsePreprocessor> responsePreprocessors = getResponsePreprocessors(configuration);
OperationResponse operationResponse = this.responseConverter.convert(response);
for (OperationResponsePreprocessor preprocessor : responsePreprocessors) {
operationResponse = preprocessor.preprocess(operationResponse);
}
return operationResponse;
}
private List<OperationResponsePreprocessor> getResponsePreprocessors(Map<String, Object> configuration) {
List<OperationResponsePreprocessor> preprocessors = new ArrayList<>(2);
preprocessors.add(this.responsePreprocessor);
OperationResponsePreprocessor defaultResponsePreprocessor = (OperationResponsePreprocessor) configuration.get(
RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR);
if (defaultResponsePreprocessor != null) {
preprocessors.add(defaultResponsePreprocessor);
}
return preprocessors;
}
private static final class IdentityOperationRequestPreprocessor
implements OperationRequestPreprocessor {

105
spring-restdocs-core/src/test/java/org/springframework/restdocs/RestDocumentationGeneratorTests.java
View File

@@ -35,8 +35,10 @@ import org.springframework.restdocs.operation.OperationResponse;
import org.springframework.restdocs.operation.OperationResponseFactory;
import org.springframework.restdocs.operation.RequestConverter;
import org.springframework.restdocs.operation.ResponseConverter;
import org.springframework.restdocs.operation.preprocess.OperationPreprocessor;
import org.springframework.restdocs.operation.preprocess.OperationRequestPreprocessor;
import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
import org.springframework.restdocs.operation.preprocess.Preprocessors;
import org.springframework.restdocs.snippet.Snippet;
import static org.hamcrest.CoreMatchers.equalTo;
@@ -51,6 +53,7 @@ import static org.mockito.Mockito.verifyNoMoreInteractions;
* Tests for {@link RestDocumentationGenerator}.
*
* @author Andy Wilkinson
* @author Filip Hrisafov
*/
public class RestDocumentationGeneratorTests {
@@ -75,6 +78,9 @@ public class RestDocumentationGeneratorTests {
private final Snippet snippet = mock(Snippet.class);
private final OperationPreprocessor requestPreprocessor = mock(OperationPreprocessor.class);
private final OperationPreprocessor responsePreprocessor = mock(OperationPreprocessor.class);
@Test
public void basicHandling() throws IOException {
given(this.requestConverter.convert(this.request))
@@ -107,6 +113,84 @@ public class RestDocumentationGeneratorTests {
verifySnippetInvocation(defaultSnippet2, configuration);
}
@Test
public void defaultOperationRequestPreprocessorsAreCalled() throws IOException {
given(this.requestConverter.convert(this.request))
.willReturn(this.operationRequest);
given(this.responseConverter.convert(this.response))
.willReturn(this.operationResponse);
HashMap<String, Object> configuration = new HashMap<>();
OperationPreprocessor defaultPreprocessor1 = mock(OperationPreprocessor.class);
OperationPreprocessor defaultPreprocessor2 = mock(OperationPreprocessor.class);
configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR,
Preprocessors.preprocessRequest(defaultPreprocessor1, defaultPreprocessor2));
OperationRequest first = createRequest();
OperationRequest second = createRequest();
OperationRequest third = createRequest();
given(this.requestPreprocessor.preprocess(this.operationRequest)).willReturn(first);
given(defaultPreprocessor1.preprocess(first)).willReturn(second);
given(defaultPreprocessor2.preprocess(second)).willReturn(third);
new RestDocumentationGenerator<>("id", this.requestConverter,
this.responseConverter, Preprocessors.preprocessRequest(this.requestPreprocessor), this.snippet)
.handle(this.request, this.response, configuration);
verifySnippetInvocation(this.snippet, third, this.operationResponse, configuration, 1);
}
@Test
public void defaultOperationResponsePreprocessorsAreCalled() throws IOException {
given(this.requestConverter.convert(this.request))
.willReturn(this.operationRequest);
given(this.responseConverter.convert(this.response))
.willReturn(this.operationResponse);
HashMap<String, Object> configuration = new HashMap<>();
OperationPreprocessor defaultPreprocessor1 = mock(OperationPreprocessor.class);
OperationPreprocessor defaultPreprocessor2 = mock(OperationPreprocessor.class);
configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR,
Preprocessors.preprocessResponse(defaultPreprocessor1, defaultPreprocessor2));
OperationResponse first = createResponse();
OperationResponse second = createResponse();
OperationResponse third = new OperationResponseFactory().createFrom(this.operationResponse, new HttpHeaders());
given(this.responsePreprocessor.preprocess(this.operationResponse)).willReturn(first);
given(defaultPreprocessor1.preprocess(first)).willReturn(second);
given(defaultPreprocessor2.preprocess(second)).willReturn(third);
new RestDocumentationGenerator<>("id", this.requestConverter,
this.responseConverter, Preprocessors.preprocessResponse(this.responsePreprocessor), this.snippet)
.handle(this.request, this.response, configuration);
verifySnippetInvocation(this.snippet, this.operationRequest, third, configuration, 1);
}
@Test
public void defaultOperationPreprocessorsAreCalled() throws IOException {
given(this.requestConverter.convert(this.request))
.willReturn(this.operationRequest);
given(this.responseConverter.convert(this.response))
.willReturn(this.operationResponse);
HashMap<String, Object> configuration = new HashMap<>();
OperationPreprocessor requestPreprocessor1 = mock(OperationPreprocessor.class);
configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR,
Preprocessors.preprocessRequest(requestPreprocessor1));
OperationRequest firstRequest = createRequest();
OperationRequest secondRequest = createRequest();
given(this.requestPreprocessor.preprocess(this.operationRequest)).willReturn(firstRequest);
given(requestPreprocessor1.preprocess(firstRequest)).willReturn(secondRequest);
OperationPreprocessor responsePreprocessor1 = mock(OperationPreprocessor.class);
configuration.put(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR,
Preprocessors.preprocessResponse(responsePreprocessor1));
OperationResponse firstResponse = createResponse();
OperationResponse secondResponse = createResponse();
given(this.responsePreprocessor.preprocess(this.operationResponse)).willReturn(firstResponse);
given(responsePreprocessor1.preprocess(firstResponse)).willReturn(secondResponse);
new RestDocumentationGenerator<>("id", this.requestConverter,
this.responseConverter, Preprocessors.preprocessRequest(this.requestPreprocessor),
Preprocessors.preprocessResponse(this.responsePreprocessor), this.snippet)
.handle(this.request, this.response, configuration);
verifySnippetInvocation(this.snippet, secondRequest, secondResponse, configuration, 1);
}
@Test
public void newGeneratorOnlyCallsItsSnippets() throws IOException {
OperationRequestPreprocessor requestPreprocessor = mock(
@@ -141,12 +225,27 @@ public class RestDocumentationGeneratorTests {
private void verifySnippetInvocation(Snippet snippet, Map<String, Object> attributes,
int times) throws IOException {
verifySnippetInvocation(snippet, this.operationRequest, this.operationResponse, attributes, times);
}
private void verifySnippetInvocation(Snippet snippet, OperationRequest operationRequest,
OperationResponse operationResponse,
Map<String, Object> attributes, int times) throws IOException {
ArgumentCaptor<Operation> operation = ArgumentCaptor.forClass(Operation.class);
verify(snippet, Mockito.times(times)).document(operation.capture());
assertThat(this.operationRequest, is(equalTo(operation.getValue().getRequest())));
assertThat(this.operationResponse,
is(equalTo(operation.getValue().getResponse())));
assertThat(operationRequest, is(equalTo(operation.getValue().getRequest())));
assertThat(operationResponse, is(equalTo(operation.getValue().getResponse())));
assertThat(attributes, is(equalTo(operation.getValue().getAttributes())));
}
private static OperationRequest createRequest() {
return new OperationRequestFactory()
.create(URI.create("http://localhost:8080"), null, null, new HttpHeaders(), null, null);
}
private static OperationResponse createResponse() {
return new OperationResponseFactory()
.create(null, null, null);
}
}

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

@@ -31,6 +31,9 @@ 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.operation.preprocess.OperationRequestPreprocessor;
import org.springframework.restdocs.operation.preprocess.OperationResponsePreprocessor;
import org.springframework.restdocs.operation.preprocess.Preprocessors;
import org.springframework.restdocs.payload.RequestBodySnippet;
import org.springframework.restdocs.payload.ResponseBodySnippet;
import org.springframework.restdocs.snippet.Snippet;
@@ -45,6 +48,7 @@ import org.springframework.test.util.ReflectionTestUtils;
import static org.hamcrest.CoreMatchers.equalTo;
import static org.hamcrest.CoreMatchers.instanceOf;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.CoreMatchers.nullValue;
import static org.hamcrest.Matchers.contains;
import static org.hamcrest.Matchers.hasEntry;
import static org.junit.Assert.assertThat;
@@ -54,6 +58,7 @@ import static org.mockito.Mockito.mock;
* Tests for {@link RestDocumentationConfigurer}.
*
* @author Andy Wilkinson
* @author Filip Hrisafov
*/
public class RestDocumentationConfigurerTests {
@@ -88,6 +93,14 @@ public class RestDocumentationConfigurerTests {
assertThat(snippetConfiguration.getEncoding(), is(equalTo("UTF-8")));
assertThat(snippetConfiguration.getTemplateFormat(),
is(equalTo(TemplateFormats.asciidoctor())));
OperationRequestPreprocessor defaultOperationRequestPreprocessor = (OperationRequestPreprocessor)
configuration.get(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR);
assertThat(defaultOperationRequestPreprocessor, is(nullValue()));
OperationResponsePreprocessor defaultOperationResponsePreprocessor = (OperationResponsePreprocessor)
configuration.get(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR);
assertThat(defaultOperationResponsePreprocessor, is(nullValue()));
}
@Test
@@ -200,6 +213,32 @@ public class RestDocumentationConfigurerTests {
assertThat(templateContext.size(), equalTo(0));
}
@Test
public void customDefaultOperationRequestPreprocessor() {
Map<String, Object> configuration = new HashMap<>();
this.configurer.operationPreprocessors()
.withDefaultRequestPreprocessors(Preprocessors.prettyPrint(), Preprocessors.removeHeaders("Foo"))
.apply(configuration, createContext());
assertThat(configuration,
hasEntry(
equalTo(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_REQUEST_PREPROCESSOR),
instanceOf(OperationRequestPreprocessor.class)));
//TODO how can we actually test that the preprocessors that we set are actually there?
}
@Test
public void customDefaultOperationResponsePreprocessor() {
Map<String, Object> configuration = new HashMap<>();
this.configurer.operationPreprocessors()
.withDefaultResponsePreprocessors(Preprocessors.prettyPrint(), Preprocessors.removeHeaders("Foo"))
.apply(configuration, createContext());
assertThat(configuration,
hasEntry(
equalTo(RestDocumentationGenerator.ATTRIBUTE_NAME_DEFAULT_OPERATION_RESPONSE_PREPROCESSOR),
instanceOf(OperationResponsePreprocessor.class)));
//TODO same as for the customDefaultOperationRequestPreprocessor
}
private RestDocumentationContext createContext() {
ManualRestDocumentation manualRestDocumentation = new ManualRestDocumentation(
"build");
@@ -209,16 +248,24 @@ public class RestDocumentationConfigurerTests {
}
private static final class TestRestDocumentationConfigurer extends
RestDocumentationConfigurer<TestSnippetConfigurer, TestRestDocumentationConfigurer> {
RestDocumentationConfigurer<TestSnippetConfigurer, TestOperationPreprocessorsConfigurer,
TestRestDocumentationConfigurer> {
private final TestSnippetConfigurer snippetConfigurer = new TestSnippetConfigurer(
this);
private final TestOperationPreprocessorsConfigurer operationPreprocessorsConfigurer =
new TestOperationPreprocessorsConfigurer(this);
@Override
public TestSnippetConfigurer snippets() {
return this.snippetConfigurer;
}
@Override
public TestOperationPreprocessorsConfigurer operationPreprocessors() {
return this.operationPreprocessorsConfigurer;
}
}
private static final class TestSnippetConfigurer extends
@@ -230,4 +277,12 @@ public class RestDocumentationConfigurerTests {
}
private static final class TestOperationPreprocessorsConfigurer extends
OperationPreprocessorsConfigurer<TestRestDocumentationConfigurer, TestOperationPreprocessorsConfigurer> {
protected TestOperationPreprocessorsConfigurer(TestRestDocumentationConfigurer parent) {
super(parent);
}
}
}