Issue #214 Added support for page breaks (#226)

* Added support for page breaks
* Added documentation and config file support for page breaks and regex

Author: cascer1

RELEASENOTES.adoc

@@ -114,4 +114,12 @@
 * Issue #205: Fixed the option to influence resource ordering
 * Issue #198: Chinese chinese language encoding
 * Issue #207: Properties that start with an underscore are displayed correctly now
-* Refactored Swagger2Markup to use a Component-Based design. A document can be composed of components and components can be composed of other components.
+* Refactored Swagger2Markup to use a Component-Based design. A document can be composed of components and components can be composed of other components.
+
+=== Version 1.1.2
+* Issue #214: Add page break locations
+* Issue #223: Improve example rendering
+* Issue #215: Add ability to group operations by RegEx
+* Added new configuration options: pageBreakLocations, headerRegex
+* Added new valid value for configuration headerRegex: REGEX
+* Updated markup-document-builder from 1.1.0 to 1.1.1-SNAPSHOT

build.gradle

@@ -13,7 +13,7 @@ buildscript {
     }
 }
 description = 'swagger2markup Build'
-version = '1.1.2-SNAPSHOT'
+version = '1.2.0'
 ext.releaseVersion = '1.1.1'
 group = 'io.github.swagger2markup'
 
@@ -41,7 +41,7 @@ repositories {
 }
 
 dependencies {
-    compile 'io.github.swagger2markup:markup-document-builder:1.1.0'
+    compile 'io.github.swagger2markup:markup-document-builder:1.1.1-SNAPSHOT'
     compile 'io.swagger:swagger-compat-spec-parser:1.0.23'
     compile 'org.apache.commons:commons-configuration2:2.1'
     compile 'commons-beanutils:commons-beanutils:1.9.2'

src/docs/asciidoc/usage_guide.adoc

@@ -136,14 +136,15 @@ The following tables list all available properties of Swagger2Markup:
 |Name | Description |  Possible Values | Default
 |swagger2markup.markupLanguage| Specifies the markup language which should be used to generate the files. | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | ASCIIDOC
 |swagger2markup.swaggerMarkupLanguage| Specifies the markup language used in Swagger descriptions. | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | MARKDOWN
-|swagger2markup.pathsGroupedBy| Specifies how the paths should be grouped | AS_IS, TAGS | AS_IS
+|swagger2markup.pathsGroupedBy| Specifies how the paths should be grouped | AS_IS, TAGS, REGEX | AS_IS
 |swagger2markup.outputLanguage| Specifies the language of the labels | EN, DE, FR, RU | EN
 |swagger2markup.lineSeparator| Specifies the line separator which should be used | UNIX, WINDOWS, MAC | <System-dependent>
 |swagger2markup.generatedExamplesEnabled| Specifies if HTTP request and response examples should be generated | true, false | false
 |swagger2markup.flatBodyEnabled| Optionally isolate the body parameter, if any, from other parameters | true, false | false
 |swagger2markup.pathSecuritySectionEnabled| Optionally disable the security section for path sections | true, false | true
 |swagger2markup.anchorPrefix| Optionally prefix all anchors for uniqueness if you want to include generated documents into a global documentation | Any String |
 |swagger2markup.basePathPrefixEnabled| Prepend the basePath to all paths | true, false | false
+|swagger2markup.headerRegex | Regular expression to use when grouping by RegEx | Any valid RegEx pattern with at least one capture group |
 |===
 
 [options="header"]
@@ -193,6 +194,13 @@ The following tables list all available properties of Swagger2Markup:
 |swagger2markup.inlineSchemaEnabled| Enable inline object schema support | true, false | true
 |===
 
+[options="header"]
+.Properties which configure page breaking
+|===
+|Name | Description | Possible Values | Default
+|swagger2markup.pageBreakLocations | Specifies where page breaks should be inserted. | BEFORE_OPERATION, BEFORE_OPERATION_DESCRIPTION, BEFORE_OPERATION_PARAMETERS, BEFORE_OPERATION_RESPONSES, BEFORE_OPERATION_CONSUMES, BEFORE_OPERATION_PRODUCES, BEFORE_OPERATION_EXAMPLE_REQUEST, BEFORE_OPERATION_EXAMPLE_RESPONSE, BEFORE_DEFINITION, AFTER_OPERATION, AFTER_OPERATION_DESCRIPTION, AFTER_OPERATION_PARAMETERS, AFTER_OPERATION_RESPONSES, AFTER_OPERATION_CONSUMES, AFTER_OPERATION_PRODUCES, AFTER_OPERATION_EXAMPLE_REQUEST, AFTER_OPERATION_EXAMPLE_RESPONSE, AFTER_DEFINITION | empty
+|===
+
 === Logging
 
 Swagger2Markup uses http://www.slf4j.org/[SLF4J] for all internal logging, but leaves the underlying log implementation open. To change the log level, you have the set the log level of the `io.github.swagger2markup` package.

src/main/java/io/github/swagger2markup/PageBreakLocations.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2016 Robert Winkler
+ *
+ * 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 io.github.swagger2markup;
+
+public enum PageBreakLocations {
+    BEFORE_OPERATION,
+    BEFORE_OPERATION_DESCRIPTION,
+    BEFORE_OPERATION_PARAMETERS,
+    BEFORE_OPERATION_RESPONSES,
+    BEFORE_OPERATION_CONSUMES,
+    BEFORE_OPERATION_PRODUCES,
+    BEFORE_OPERATION_EXAMPLE_REQUEST,
+    BEFORE_OPERATION_EXAMPLE_RESPONSE,
+    BEFORE_DEFINITION,
+    AFTER_OPERATION,
+    AFTER_OPERATION_DESCRIPTION,
+    AFTER_OPERATION_PARAMETERS,
+    AFTER_OPERATION_RESPONSES,
+    AFTER_OPERATION_CONSUMES,
+    AFTER_OPERATION_PRODUCES,
+    AFTER_OPERATION_EXAMPLE_REQUEST,
+    AFTER_OPERATION_EXAMPLE_RESPONSE,
+    AFTER_DEFINITION
+}

src/main/java/io/github/swagger2markup/Swagger2MarkupConfig.java

@@ -21,6 +21,7 @@
 import io.swagger.models.parameters.Parameter;
 
 import java.util.Comparator;
+import java.util.List;
 import java.util.regex.Pattern;
 
 /**
@@ -219,4 +220,11 @@ public interface Swagger2MarkupConfig {
      * @return the extension properties
      */
     Swagger2MarkupProperties getExtensionsProperties();
+
+    /**
+     * Returns the list of page break locations
+     *
+     * @return List of PageBreakLocations
+     */
+    List<PageBreakLocations> getPageBreakLocations();
 }

src/main/java/io/github/swagger2markup/Swagger2MarkupProperties.java

@@ -25,10 +25,8 @@
 import java.net.URI;
 import java.nio.file.Path;
 import java.nio.file.Paths;
-import java.util.List;
-import java.util.Map;
-import java.util.Optional;
-import java.util.Properties;
+import java.util.*;
+import java.util.regex.Pattern;
 
 public class Swagger2MarkupProperties {
 
@@ -65,6 +63,7 @@ public class Swagger2MarkupProperties {
     public static final String PROPERTY_ORDER_BY = PROPERTIES_PREFIX + ".propertyOrderBy";
     public static final String RESPONSE_ORDER_BY = PROPERTIES_PREFIX + ".responseOrderBy";
     public static final String LINE_SEPARATOR = PROPERTIES_PREFIX + ".lineSeparator";
+    public static final String PAGE_BREAK_LOCATIONS = PROPERTIES_PREFIX + ".pageBreakLocations";
 
     /**
      * Prefix for Swagger2Markup extension properties
@@ -337,4 +336,20 @@ public List<String> getKeys() {
     public List<String> getKeys(String prefix) {
         return IteratorUtils.toList(configuration.getKeys(prefix));
     }
+
+    public List<PageBreakLocations> getPageBreakLocations(String key) {
+        List result = configuration.getList(PageBreakLocations.class, key);
+        if(result == null) result = new ArrayList<PageBreakLocations>();
+
+        return result;
+    }
+
+    public Optional<Pattern> getHeaderPattern(String key) {
+        Optional<String> property = getString(key);
+        if (property.isPresent()) {
+            return Optional.of(Pattern.compile(property.get()));
+        } else {
+            return Optional.empty();
+        }
+    }
 }

src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java

@@ -30,10 +30,7 @@
 import org.apache.commons.lang3.StringUtils;
 import org.apache.commons.lang3.Validate;
 
-import java.util.Comparator;
-import java.util.Map;
-import java.util.Optional;
-import java.util.Properties;
+import java.util.*;
 import java.util.regex.Pattern;
 import java.util.regex.PatternSyntaxException;
 
@@ -107,6 +104,12 @@ public Swagger2MarkupConfigBuilder(Configuration configuration) {
             config.lineSeparator = LineSeparator.valueOf(lineSeparator.get());
         }
 
+        config.pageBreakLocations = swagger2MarkupProperties.getPageBreakLocations(PAGE_BREAK_LOCATIONS);
+
+        Optional<Pattern> headerPattern = swagger2MarkupProperties.getHeaderPattern(HEADER_REGEX);
+
+        config.headerPattern = headerPattern.orElse(null);
+
         Configuration swagger2markupConfiguration = compositeConfiguration.subset(PROPERTIES_PREFIX);
         Configuration extensionsConfiguration = swagger2markupConfiguration.subset(EXTENSION_PREFIX);
         config.extensionsProperties = new Swagger2MarkupProperties(extensionsConfiguration);
@@ -486,11 +489,23 @@ public Swagger2MarkupConfigBuilder withBasePathPrefix() {
      * @return this builder
      */
     public Swagger2MarkupConfigBuilder withAnchorPrefix(String anchorPrefix) {
-        Validate.notNull(anchorPrefix, "%s must no be null", "anchorPrefix");
+        Validate.notNull(anchorPrefix, "%s must not be null", "anchorPrefix");
         config.anchorPrefix = anchorPrefix;
         return this;
     }
 
+    /**
+     * Set the page break locations
+     *
+     * @param locations List of locations to create new pages
+     * @return this builder
+     */
+    public Swagger2MarkupConfigBuilder withPageBreaks(List<PageBreakLocations> locations) {
+        Validate.notNull(locations, "%s must not be null", "locations");
+        config.pageBreakLocations = locations;
+        return this;
+    }
+
     /**
      * Specifies the line separator which should be used.
      *
@@ -540,6 +555,8 @@ static class DefaultSwagger2MarkupConfig implements Swagger2MarkupConfig {
         private String separatedOperationsFolder;
         private String separatedDefinitionsFolder;
 
+        private List<PageBreakLocations> pageBreakLocations;
+
         private Pattern headerPattern;
 
         private Swagger2MarkupProperties extensionsProperties;
@@ -718,5 +735,10 @@ public Swagger2MarkupProperties getExtensionsProperties() {
         public boolean isBasePathPrefixEnabled() {
             return basePathPrefixEnabled;
         }
+
+        @Override
+        public List<PageBreakLocations> getPageBreakLocations() {
+            return pageBreakLocations;
+        }
     }
 }

src/main/java/io/github/swagger2markup/internal/component/PathOperationComponent.java

@@ -20,6 +20,7 @@
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.github.swagger2markup.GroupBy;
+import io.github.swagger2markup.PageBreakLocations;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.internal.resolver.DocumentResolver;
 import io.github.swagger2markup.internal.type.ObjectType;
@@ -41,6 +42,7 @@
 import java.util.*;
 
 import static io.github.swagger2markup.Labels.*;
+import static io.github.swagger2markup.PageBreakLocations.*;
 import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.copyMarkupDocBuilder;
 import static io.github.swagger2markup.internal.utils.MarkupDocBuilderUtils.markupDescription;
 import static io.github.swagger2markup.spi.PathsDocumentExtension.Position;
@@ -80,21 +82,46 @@ public static PathOperationComponent.Parameters parameters(PathOperation operati
     @Override
     public MarkupDocBuilder apply(MarkupDocBuilder markupDocBuilder, Parameters params) {
         PathOperation operation = params.operation;
+        List<PageBreakLocations> locations = config.getPageBreakLocations();
+
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_BEFORE, markupDocBuilder, operation));
+
+        if (locations.contains(BEFORE_OPERATION)) markupDocBuilder.pageBreak();
         buildOperationTitle(markupDocBuilder, operation);
+
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_BEGIN, markupDocBuilder, operation));
         buildDeprecatedSection(markupDocBuilder, operation);
+
+        if (locations.contains(BEFORE_OPERATION_DESCRIPTION)) markupDocBuilder.pageBreak();
         buildDescriptionSection(markupDocBuilder, operation);
+        if (locations.contains(AFTER_OPERATION_DESCRIPTION)) markupDocBuilder.pageBreak();
+
+        if (locations.contains(BEFORE_OPERATION_PARAMETERS)) markupDocBuilder.pageBreak();
         inlineDefinitions(markupDocBuilder, buildParametersSection(markupDocBuilder, operation), operation.getPath() + " " + operation.getMethod());
+        if (locations.contains(AFTER_OPERATION_PARAMETERS)) markupDocBuilder.pageBreak();
+
         inlineDefinitions(markupDocBuilder, buildBodyParameterSection(markupDocBuilder, operation), operation.getPath() + " " + operation.getMethod());
+
+        if (locations.contains(BEFORE_OPERATION_RESPONSES)) markupDocBuilder.pageBreak();
         inlineDefinitions(markupDocBuilder, buildResponsesSection(markupDocBuilder, operation), operation.getPath() + " " + operation.getMethod());
+        if (locations.contains(AFTER_OPERATION_RESPONSES)) markupDocBuilder.pageBreak();
+
+        if (locations.contains(BEFORE_OPERATION_CONSUMES)) markupDocBuilder.pageBreak();
         buildConsumesSection(markupDocBuilder, operation);
+        if (locations.contains(AFTER_OPERATION_CONSUMES)) markupDocBuilder.pageBreak();
+
+        if (locations.contains(BEFORE_OPERATION_PRODUCES)) markupDocBuilder.pageBreak();
         buildProducesSection(markupDocBuilder, operation);
+        if (locations.contains(AFTER_OPERATION_PRODUCES)) markupDocBuilder.pageBreak();
+
         buildTagsSection(markupDocBuilder, operation);
         buildSecuritySchemeSection(markupDocBuilder, operation);
-        buildExamplesSection(markupDocBuilder, operation);
+        buildExamplesSection(markupDocBuilder, operation, locations);
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_END, markupDocBuilder, operation));
         applyPathsDocumentExtension(new PathsDocumentExtension.Context(Position.OPERATION_AFTER, markupDocBuilder, operation));
+
+        if (locations.contains(AFTER_OPERATION)) markupDocBuilder.pageBreak();
+
         return markupDocBuilder;
     }
 
@@ -317,17 +344,23 @@ private int getSectionTitleLevel() {
      *
      * @param operation the Swagger Operation
      */
-    private void buildExamplesSection(MarkupDocBuilder markupDocBuilder, PathOperation operation) {
+    private void buildExamplesSection(MarkupDocBuilder markupDocBuilder, PathOperation operation, List<PageBreakLocations> locations) {
 
         Map<String, Object> generatedRequestExampleMap = ExamplesUtil.generateRequestExampleMap(config.isGeneratedExamplesEnabled(), operation, definitions, definitionDocumentResolver, markupDocBuilder);
         Map<String, Object> generatedResponseExampleMap = ExamplesUtil.generateResponseExampleMap(config.isGeneratedExamplesEnabled(), operation, definitions, definitionDocumentResolver, markupDocBuilder);
 
-        exampleMap(markupDocBuilder, generatedRequestExampleMap, labels.getLabel(EXAMPLE_REQUEST), labels.getLabel(REQUEST));
-        exampleMap(markupDocBuilder, generatedResponseExampleMap, labels.getLabel(EXAMPLE_RESPONSE), labels.getLabel(RESPONSE));
+        boolean beforeExampleRequestBreak = locations.contains(BEFORE_OPERATION_EXAMPLE_REQUEST);
+        boolean afterExampleRequestBreak = locations.contains(AFTER_OPERATION_EXAMPLE_REQUEST);
+        boolean beforeExampleResponseBreak = locations.contains(BEFORE_OPERATION_EXAMPLE_RESPONSE);
+        boolean afterExampleResponseBreak = locations.contains(AFTER_OPERATION_EXAMPLE_RESPONSE);
+
+        exampleMap(markupDocBuilder, generatedRequestExampleMap, labels.getLabel(EXAMPLE_REQUEST), labels.getLabel(REQUEST), beforeExampleRequestBreak, afterExampleRequestBreak);
+        exampleMap(markupDocBuilder, generatedResponseExampleMap, labels.getLabel(EXAMPLE_RESPONSE), labels.getLabel(RESPONSE), beforeExampleResponseBreak, afterExampleResponseBreak);
     }
 
-    private void exampleMap(MarkupDocBuilder markupDocBuilder, Map<String, Object> exampleMap, String operationSectionTitle, String sectionTitle) {
+    private void exampleMap(MarkupDocBuilder markupDocBuilder, Map<String, Object> exampleMap, String operationSectionTitle, String sectionTitle, boolean beforeBreak, boolean afterBreak) {
         if (exampleMap.size() > 0) {
+            if (beforeBreak) markupDocBuilder.pageBreak();
             buildSectionTitle(markupDocBuilder, operationSectionTitle);
             for (Map.Entry<String, Object> entry : exampleMap.entrySet()) {
 
@@ -376,6 +409,7 @@ private void exampleMap(MarkupDocBuilder markupDocBuilder, Map<String, Object> e
                     markupDocBuilder.listingBlock(Json.pretty(entry.getValue()), "json");
                 }
             }
+            if (afterBreak) markupDocBuilder.pageBreak();
         }
     }