Support for translations (#189)

* Support for translations

* pr feedback

Author: jmisur

docs/index.html

@@ -467,6 +467,7 @@ <h1>Spring Auto REST Docs</h1>
 <li><a href="#paging">Paging support</a></li>
 <li><a href="#preprocessors">Preprocessors</a></li>
 <li><a href="#deprecation">Deprecation support</a></li>
+<li><a href="#localization">Localization support</a></li>
 </ul>
 </li>
 <li><a href="#contributing">Contributing</a>
@@ -1669,6 +1670,22 @@ <h3 id="deprecation"><a class="link" href="#deprecation">Deprecation support</a>
 See how it looks in the <a href="https://htmlpreview.github.io/?https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-example/generated-docs/index.html#resources-item-resource-test-clone-item">example project</a>.</p>
 </div>
 </div>
+<div class="sect2">
+<h3 id="localization"><a class="link" href="#localization">Localization support</a></h3>
+<div class="paragraph">
+<p>For custom translations of section titles, table headers and other messages:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>Create a file <code>SnippetMessages.properties</code> in <code>capital.scalable.restdocs.i18n</code> package.</p>
+</li>
+<li>
+<p>Add translations to the file using keys from <a href="https://github.com/ScaCap/spring-auto-restdocs/blob/master/spring-auto-restdocs-core/src/test/resources/capital/scalable/restdocs/i18n/DefaultSnippetMessages.properties">DefaultSnippetMessages</a>.</p>
+</li>
+</ol>
+</div>
+</div>
 </div>
 </div>
 <div class="sect1">
@@ -1750,7 +1767,7 @@ <h4 id="contributing-building-build"><a class="link" href="#contributing-buildin
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2017-12-01 21:41:24 CET
+Last updated 2018-01-03 12:37:41 CET
 </div>
 </div>
 <link rel="stylesheet" href="highlight/styles/github.min.css">

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/SnippetRegistry.java

@@ -24,10 +24,10 @@ public class SnippetRegistry {
 
     static {
         CLASSIC_SNIPPETS = new HashMap<>();
-        CLASSIC_SNIPPETS.put(CURL_REQUEST, section(CURL_REQUEST, "Example request", true));
-        CLASSIC_SNIPPETS.put(HTTPIE_REQUEST, section(HTTPIE_REQUEST, "Example request", true));
-        CLASSIC_SNIPPETS.put(HTTP_REQUEST, section(HTTP_REQUEST, "Example request", true));
-        CLASSIC_SNIPPETS.put(HTTP_RESPONSE, section(HTTP_RESPONSE, "Example response", true));
+        CLASSIC_SNIPPETS.put(CURL_REQUEST, section(CURL_REQUEST, "example-request", true));
+        CLASSIC_SNIPPETS.put(HTTPIE_REQUEST, section(HTTPIE_REQUEST, "example-request", true));
+        CLASSIC_SNIPPETS.put(HTTP_REQUEST, section(HTTP_REQUEST, "example-request", true));
+        CLASSIC_SNIPPETS.put(HTTP_RESPONSE, section(HTTP_RESPONSE, "example-response", true));
     }
 
     public static SectionSupport getClassicSnippet(String snippetName) {
@@ -40,12 +40,12 @@ private static SectionSupport section(String snippetName, String header, boolean
 
     private static class ClassicSnippetSection implements SectionSupport {
         private String fileName;
-        private String header;
+        private String headerKey;
         private boolean hasContent;
 
-        public ClassicSnippetSection(String fileName, String header, boolean hasContent) {
+        public ClassicSnippetSection(String fileName, String headerKey, boolean hasContent) {
             this.fileName = fileName;
-            this.header = header;
+            this.headerKey = headerKey;
             this.hasContent = hasContent;
         }
 
@@ -55,8 +55,8 @@ public String getFileName() {
         }
 
         @Override
-        public String getHeader() {
-            return header;
+        public String getHeaderKey() {
+            return headerKey;
         }
 
         @Override

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/i18n/SnippetTranslationResolver.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright 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 capital.scalable.restdocs.i18n;
+
+import java.util.Locale;
+import java.util.MissingResourceException;
+import java.util.ResourceBundle;
+
+/**
+ * Inspired by
+ * {@link org.springframework.restdocs.constraints.ResourceBundleConstraintDescriptionResolver}
+ */
+public class SnippetTranslationResolver {
+
+    private static ResourceBundle defaultMessages = getBundle("DefaultSnippetMessages");
+
+    private static ResourceBundle userMessages = getBundle("SnippetMessages");
+
+    private static ResourceBundle getBundle(String name) {
+        try {
+            return ResourceBundle.getBundle(
+                    SnippetTranslationResolver.class.getPackage()
+                            .getName() + "." + name,
+                    Locale.getDefault(), Thread.currentThread().getContextClassLoader());
+        } catch (MissingResourceException ex) {
+            return null;
+        }
+    }
+
+    public static String translate(String key) {
+        try {
+            if (userMessages != null) {
+                return userMessages.getString(key);
+            }
+        } catch (MissingResourceException ex) {
+            // Continue and return default description, if available
+        }
+        return defaultMessages.getString(key);
+    }
+
+    // visible for testing
+    public static void setUserMessages(String name) {
+        userMessages = getBundle(name);
+    }
+}

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/misc/AuthorizationSnippet.java

@@ -66,8 +66,8 @@ public String getFileName() {
     }
 
     @Override
-    public String getHeader() {
-        return "Authorization";
+    public String getHeaderKey() {
+        return "authorization";
     }
 
     @Override

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/payload/AbstractJacksonFieldSnippet.java

@@ -20,6 +20,7 @@
 import static capital.scalable.restdocs.OperationAttributeHelper.getHandlerMethod;
 import static capital.scalable.restdocs.OperationAttributeHelper.getJavadocReader;
 import static capital.scalable.restdocs.OperationAttributeHelper.getObjectMapper;
+import static capital.scalable.restdocs.i18n.SnippetTranslationResolver.translate;
 import static capital.scalable.restdocs.util.FieldDescriptorUtil.assertAllDocumented;
 
 import java.lang.reflect.ParameterizedType;
@@ -77,7 +78,7 @@ protected Collection<FieldDescriptor> createFieldDescriptors(Operation operation
         }
 
         if (shouldFailOnUndocumentedFields()) {
-            assertAllDocumented(fieldDescriptors.values(), getHeader().toLowerCase());
+            assertAllDocumented(fieldDescriptors.values(), translate(getHeaderKey()).toLowerCase());
         }
         return fieldDescriptors.values();
     }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/payload/JacksonRequestFieldSnippet.java

@@ -86,12 +86,23 @@ public Type getGenericComponentType() {
     }
 
     @Override
-    public String getHeader() {
-        return "Request fields";
+    public String getHeaderKey() {
+        return "request-fields";
     }
 
     @Override
     protected boolean shouldFailOnUndocumentedFields() {
         return failOnUndocumentedFields;
     }
+
+    @Override
+    protected String[] getTranslationKeys() {
+        return new String[]{
+                "th-path",
+                "th-type",
+                "th-optional",
+                "th-description",
+                "no-request-body"
+        };
+    }
 }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/payload/JacksonResponseFieldSnippet.java

@@ -89,12 +89,25 @@ private boolean isPageResponse(HandlerMethod handlerMethod) {
     }
 
     @Override
-    public String getHeader() {
-        return "Response fields";
+    public String getHeaderKey() {
+        return "response-fields";
     }
 
     @Override
     protected boolean shouldFailOnUndocumentedFields() {
         return failOnUndocumentedFields;
     }
+
+    @Override
+    protected String[] getTranslationKeys() {
+        return new String[]{
+                "th-path",
+                "th-type",
+                "th-optional",
+                "th-description",
+                "pagination-response-adoc",
+                "pagination-response-md",
+                "no-response-body"
+        };
+    }
 }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/request/AbstractParameterSnippet.java

@@ -23,6 +23,7 @@
 import static capital.scalable.restdocs.constraints.ConstraintReader.DEFAULT_VALUE_ATTRIBUTE;
 import static capital.scalable.restdocs.constraints.ConstraintReader.DEPRECATED_ATTRIBUTE;
 import static capital.scalable.restdocs.constraints.ConstraintReader.OPTIONAL_ATTRIBUTE;
+import static capital.scalable.restdocs.i18n.SnippetTranslationResolver.translate;
 import static capital.scalable.restdocs.util.FieldDescriptorUtil.assertAllDocumented;
 import static capital.scalable.restdocs.util.TypeUtil.determineTypeName;
 import static java.util.Collections.singletonList;
@@ -67,7 +68,7 @@ protected List<FieldDescriptor> createFieldDescriptors(Operation operation,
         }
 
         if (shouldFailOnUndocumentedParams()) {
-            assertAllDocumented(fieldDescriptors, getHeader().toLowerCase());
+            assertAllDocumented(fieldDescriptors, translate(getHeaderKey()).toLowerCase());
         }
 
         return fieldDescriptors;

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/request/PathParametersSnippet.java

@@ -53,8 +53,8 @@ protected PathVariable getAnnotation(MethodParameter param) {
     }
 
     @Override
-    public String getHeader() {
-        return "Path parameters";
+    public String getHeaderKey() {
+        return "path-parameters";
     }
 
     @Override
@@ -67,4 +67,15 @@ protected String getDefaultValue(final PathVariable annotation) {
         // @PathVariable does not have a default value
         return null;
     }
+
+    @Override
+    protected String[] getTranslationKeys() {
+        return new String[]{
+                "th-parameter",
+                "th-type",
+                "th-optional",
+                "th-description",
+                "no-params"
+        };
+    }
 }

spring-auto-restdocs-core/src/main/java/capital/scalable/restdocs/request/RequestHeaderSnippet.java

@@ -53,8 +53,8 @@ protected RequestHeader getAnnotation(MethodParameter param) {
     }
 
     @Override
-    public String getHeader() {
-        return "Request headers";
+    public String getHeaderKey() {
+        return "request-headers";
     }
 
     @Override
@@ -66,4 +66,15 @@ protected boolean shouldFailOnUndocumentedParams() {
     protected String getDefaultValue(final RequestHeader annotation) {
         return annotation.defaultValue();
     }
+
+    @Override
+    protected String[] getTranslationKeys() {
+        return new String[]{
+                "th-header",
+                "th-type",
+                "th-optional",
+                "th-description",
+                "no-headers"
+        };
+    }
 }