Added possibility to write object definitions to separate files. Issue Swagger2Markup#19

Author: Robert Winkler

README.adoc

@@ -1,6 +1,6 @@
 = Swagger2Markup
 :author: Robert Winkler
-:version: 0.6.2
+:version: 0.6.3
 :hardbreaks:
 
 image:https://travis-ci.org/RobWin/swagger2markup.svg?branch=master["Build Status", link="https://travis-ci.org/RobWin/swagger2markup"] image:https://coveralls.io/repos/RobWin/swagger2markup/badge.svg["Coverage Status", link="https://coveralls.io/r/RobWin/swagger2markup"] image:https://api.bintray.com/packages/robwin/maven/swagger2markup/images/download.svg[link="https://bintray.com/robwin/maven/swagger2markup/_latestVersion"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"] image:https://img.shields.io/badge/Twitter-rbrtwnklr-blue.svg["Twitter", link="https://twitter.com/rbrtwnklr"] image:https://badges.gitter.im/Join%20Chat.svg[link="https://gitter.im/RobWin/swagger2markup?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"]
@@ -43,7 +43,7 @@ The project is published in JCenter and Maven Central.
 <dependency>
     <groupId>io.github.robwin</groupId>
     <artifactId>swagger2markup</artifactId>
-    <version>0.6.2</version>
+    <version>0.6.3</version>
 </dependency>
 ----
 
@@ -55,7 +55,7 @@ repositories {
     jcenter()
 }
 
-compile "io.github.robwin:swagger2markup:0.6.2"
+compile "io.github.robwin:swagger2markup:0.6.3"
 ----
 
 === Using Swagger2Markup

RELEASENOTES.adoc

@@ -51,3 +51,6 @@
 
 == Version 0.6.2
 * curl-request.adoc from spring-restdocs is also added to the example chapters
+
+== Version 0.6.3
+* Added possibility to write object definitions to separate files. Issue #19

build.gradle

@@ -13,7 +13,7 @@ buildscript {
     }
 }
 description = 'swagger2markup Build'
-version = '0.6.2'
+version = '0.6.3'
 group = 'io.github.robwin'
 
 apply plugin: 'java'

src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java

@@ -46,7 +46,7 @@ public class Swagger2MarkupConverter {
     private final String examplesFolderPath;
     private final String schemasFolderPath;
     private final String descriptionsFolderPath;
-    private final boolean isSplitDescriptions;
+    private final boolean separatedDefinitions;
     private static final String OVERVIEW_DOCUMENT = "overview";
     private static final String PATHS_DOCUMENT = "paths";
     private static final String DEFINITIONS_DOCUMENT = "definitions";
@@ -57,14 +57,15 @@ public class Swagger2MarkupConverter {
      * @param examplesFolderPath the folderPath where examples are stored
      * @param schemasFolderPath the folderPath where (XML, JSON)-Schema  files are stored
      * @param descriptionsFolderPath the folderPath where descriptions are stored
+     * @param separatedDefinitions create separate definition files for each model definition.
      */
-    Swagger2MarkupConverter(MarkupLanguage markupLanguage, Swagger swagger, String examplesFolderPath, String schemasFolderPath, String descriptionsFolderPath, boolean isSplitDescriptions){
+    Swagger2MarkupConverter(MarkupLanguage markupLanguage, Swagger swagger, String examplesFolderPath, String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions){
         this.markupLanguage = markupLanguage;
         this.swagger = swagger;
         this.examplesFolderPath = examplesFolderPath;
         this.schemasFolderPath = schemasFolderPath;
         this.descriptionsFolderPath = descriptionsFolderPath;
-        this.isSplitDescriptions = isSplitDescriptions;
+        this.separatedDefinitions = separatedDefinitions;
     }
 
     /**
@@ -137,19 +138,19 @@ public String asString() throws IOException{
     }
 
     /**
-     * Writes a file for the Paths (API) and a file for the Definitions (Model)
+     * Builds all documents and writes them to a directory
 
      * @param directory the directory where the generated file should be stored
      * @throws IOException if a file cannot be written
      */
     private void buildDocuments(String directory) throws IOException {
         new OverviewDocument(swagger, markupLanguage).build().writeToFile(directory, OVERVIEW_DOCUMENT, StandardCharsets.UTF_8);
         new PathsDocument(swagger, markupLanguage, examplesFolderPath, descriptionsFolderPath).build().writeToFile(directory, PATHS_DOCUMENT, StandardCharsets.UTF_8);
-        new DefinitionsDocument(swagger, markupLanguage, schemasFolderPath, descriptionsFolderPath, isSplitDescriptions, directory).build().writeToFile(directory, DEFINITIONS_DOCUMENT, StandardCharsets.UTF_8);
+        new DefinitionsDocument(swagger, markupLanguage, schemasFolderPath, descriptionsFolderPath, separatedDefinitions, directory).build().writeToFile(directory, DEFINITIONS_DOCUMENT, StandardCharsets.UTF_8);
     }
 
     /**
-     * Returns a file for the Paths (API) and a file for the Definitions (Model)
+     * Returns all documents as a String
 
      * @return a the document as a String
      */
@@ -165,7 +166,7 @@ public static class Builder{
         private String examplesFolderPath;
         private String schemasFolderPath;
         private String descriptionsFolderPath;
-        private boolean isSplitDescriptions;
+        private boolean separatedDefinitions;
         private MarkupLanguage markupLanguage = MarkupLanguage.ASCIIDOC;
 
         /**
@@ -190,7 +191,7 @@ public static class Builder{
         }
 
         public Swagger2MarkupConverter build(){
-            return new Swagger2MarkupConverter(markupLanguage, swagger, examplesFolderPath, schemasFolderPath, descriptionsFolderPath, isSplitDescriptions);
+            return new Swagger2MarkupConverter(markupLanguage, swagger, examplesFolderPath, schemasFolderPath, descriptionsFolderPath, separatedDefinitions);
         }
 
         /**
@@ -216,11 +217,11 @@ public Builder withDescriptions(String descriptionsFolderPath){
         }
 
         /**
-         * In addition to definitions file, also create separate definition files for each entity. 
+         * In addition to the definitions file, also create separate definition files for each model definition.
          * @return the Swagger2MarkupConverter.Builder
          */
-        public Builder withSplitDescriptions() {
-            this.isSplitDescriptions = true;
+        public Builder withSeparatedDefinitions() {
+            this.separatedDefinitions = true;
             return this;
         }
 

src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java

@@ -54,10 +54,10 @@ public class DefinitionsDocument extends MarkupDocument {
     private String schemasFolderPath;
     private boolean handWrittenDescriptionsEnabled;
     private String descriptionsFolderPath;
-    private boolean isSplitDescriptions;
+    private boolean separatedDefinitionsEnabled;
     private String outputDirectory;
 
-    public DefinitionsDocument(Swagger swagger, MarkupLanguage markupLanguage, String schemasFolderPath, String descriptionsFolderPath, boolean isSplitDescriptions, String outputDirectory){
+    public DefinitionsDocument(Swagger swagger, MarkupLanguage markupLanguage, String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitionsEnabled, String outputDirectory){
         super(swagger, markupLanguage);
         if(StringUtils.isNotBlank(schemasFolderPath)){
             this.schemasEnabled = true;
@@ -85,14 +85,18 @@ public DefinitionsDocument(Swagger swagger, MarkupLanguage markupLanguage, Strin
                 logger.debug("Include hand-written descriptions is disabled.");
             }
         }
-        this.isSplitDescriptions = isSplitDescriptions;
-        this.outputDirectory = outputDirectory;
-        if (isSplitDescriptions) {
-            Validate.notEmpty(outputDirectory, "Output directory is required for descriptions!");
+        this.separatedDefinitionsEnabled = separatedDefinitionsEnabled;
+        if(this.separatedDefinitionsEnabled){
             if (logger.isDebugEnabled()) {
-                logger.debug("Include split descriptions for each model object in path: " + outputDirectory);
+                logger.debug("Create separated definition files is enabled.");
+            }
+            Validate.notEmpty(outputDirectory, "Output directory is required for separated definition files!");
+        }else{
+            if (logger.isDebugEnabled()) {
+                logger.debug("Create separated definition files is disabled.");
             }
         }
+        this.outputDirectory = outputDirectory;
     }
 
     @Override
@@ -116,7 +120,7 @@ private void definitions(Map<String, Model> definitions, MarkupDocBuilder docBui
                     if (checkThatDefinitionIsNotInIgnoreList(definitionName)) {
                         definition(definitionName, definitionsEntry.getValue(), docBuilder);
                         definitionSchema(definitionName, docBuilder);
-                        if (isSplitDescriptions) {
+                        if (separatedDefinitionsEnabled) {
                             MarkupDocBuilder defDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage);
                             definition(definitionName, definitionsEntry.getValue(), defDocBuilder);
                             definitionSchema(definitionName, defDocBuilder);

src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java

@@ -103,14 +103,14 @@ public void testSwagger2MarkdownConversionWithDescriptions() throws IOException
     }
 
     @Test
-    public void testSwagger2AsciiDocConversionWithSplitDescriptions() throws IOException {
+    public void testSwagger2AsciiDocConversionWithSeparatedDefinitions() throws IOException {
         //Given
         File file = new File(Swagger2MarkupConverterTest.class.getResource("/json/swagger.json").getFile());
         File outputDirectory = new File("build/docs/asciidoc/generated");
         FileUtils.deleteQuietly(outputDirectory);
 
         //When
-        Swagger2MarkupConverter.from(file.getAbsolutePath()).withSplitDescriptions().build()
+        Swagger2MarkupConverter.from(file.getAbsolutePath()).withSeparatedDefinitions().build()
             .intoFolder(outputDirectory.getAbsolutePath());
 
         //Then
@@ -122,6 +122,27 @@ public void testSwagger2AsciiDocConversionWithSplitDescriptions() throws IOExcep
             .contains(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "user.adoc"))));
     }
 
+    @Test
+    public void testSwagger2MarkdownConversionWithSeparatedDefinitions() throws IOException {
+        //Given
+        File file = new File(Swagger2MarkupConverterTest.class.getResource("/json/swagger.json").getFile());
+        File outputDirectory = new File("build/docs/asciidoc/generated");
+        FileUtils.deleteQuietly(outputDirectory);
+
+        //When
+        Swagger2MarkupConverter.from(file.getAbsolutePath()).withSeparatedDefinitions().
+                withMarkupLanguage(MarkupLanguage.MARKDOWN).build()
+                .intoFolder(outputDirectory.getAbsolutePath());
+
+        //Then
+        String[] directories = outputDirectory.list();
+        assertThat(directories).hasSize(8).containsAll(
+                asList("definitions.md", "overview.md", "paths.md",
+                        "user.md", "category.md", "pet.md", "tag.md", "order.md"));
+        assertThat(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "definitions.md"))))
+                .contains(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "user.md"))));
+    }
+
     /*
     @Test
     public void testSwagger2HtmlConversion() throws IOException {