Merge remote-tracking branch 'origin/master'

Support for global responses and parameters

README.adoc

@@ -11,11 +11,20 @@ The primary goal of this project is to *simplify the generation of an up-to-date
 
 Swagger2Markup converts a Swagger JSON or YAML file into several *AsciiDoc* or *GitHub Flavored Markdown* documents which can be combined with hand-written documentation. The Swagger source file can be located locally or remotely via HTTP. Swagger2Markup supports the Swagger 1.2 and 2.0 specification. Internally it uses the _official_ https://github.com/swagger-api/swagger-parser[swagger-parser] and my https://github.com/RobWin/markup-document-builder[markup-document-builder]. 
 
-You can use Swagger2Markup to convert your contract-first Swagger YAML file into a human-readable format and combine it with hand-written documentation. As an alternative, you can choose the code-first approach and use Swagger2Markup together with https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X[Swagger JAX-RS], https://github.com/springfox/springfox[springfox] or https://github.com/spring-projects/spring-restdocs[spring-restdocs]. If you are are Gradle or Maven user, you can also use the https://github.com/RobWin/swagger2markup-gradle-plugin[Swagger2Markup Gradle Plugin] or https://github.com/redowl/swagger2markup-maven-plugin[Swagger2markup Maven Plugin].
+You can use Swagger2Markup to convert your contract-first Swagger YAML file into a human-readable format and combine it with hand-written documentation. As an alternative, you can choose the code-first approach and use Swagger2Markup together with https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-JAX-RS-Project-Setup-1.5.X[Swagger JAX-RS], https://github.com/springfox/springfox[springfox] or https://github.com/spring-projects/spring-restdocs[spring-restdocs]. If you are Gradle or Maven user, you can also use the https://github.com/RobWin/swagger2markup-gradle-plugin[Swagger2Markup Gradle Plugin] or https://github.com/redowl/swagger2markup-maven-plugin[Swagger2markup Maven Plugin].
 
 http://asciidoctor.org/docs/asciidoc-writers-guide/[AsciiDoc] is preferable to Markdown as it has more features. AsciiDoc is a text document format for writing documentation, articles, books, ebooks, slideshows, web pages and blogs. AsciiDoc files can be converted to *HTML*, *PDF* and *EPUB*. AsciiDoc is much better suited for describing public APIs than *JavaDoc* or *Annotations*.
 
-You can generate your HTML5, PDF and EPUB documentation via https://github.com/asciidoctor/asciidoctorj[asciidoctorj] or even better via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin] or https://github.com/asciidoctor/asciidoctor-maven-plugin[asciidoctor-maven-plugin]. You can also use https://readme.io/[ReadMe.io], https://github.com/jbake-org/jbake[JBake], https://github.com/tomchristie/mkdocs[MkDocs], https://github.com/rtfd/readthedocs.org[ReadTheDocs] or https://github.com/tripit/slate[slate] to publish your AsciiDoc or Markdown documentation.
+You can generate your HTML5, PDF and EPUB documentation via https://github.com/asciidoctor/asciidoctorj[asciidoctorj] or even better via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin] or https://github.com/asciidoctor/asciidoctor-maven-plugin[asciidoctor-maven-plugin]. You can publish your AsciiDoc documentation using https://github.com/RobWin/asciidocular[Asciidocular].  Asciidocular is a small AngularJS web app that loads your AsciiDoc files via Ajax and renders them as a full web site.
+
+Advantages:
+
+* No server-side components needed to convert your AsciiDoc files into HTML
+* No build process and tools needed
+* Deployable via GitHub Pages
+* Responsive Bootswatch (Bootstrap) theme
+
+You can publish your Markdown documentation using https://github.com/jbake-org/jbake[JBake], https://github.com/tomchristie/mkdocs[MkDocs] or https://github.com/rtfd/readthedocs.org[ReadTheDocs].
 
 The project requires at least JDK 7.
 
@@ -33,6 +42,8 @@ Pull requests are welcome.
 
 * New feature https://github.com/Swagger2Markup/swagger2markup/issues/21[RobWin/Swagger2Markup#21] by https://github.com/redowl[@redowl]: Support for both reference models and composed models.
 
+* New feature https://github.com/Swagger2Markup/swagger2markup/issues/27[RobWin/Swagger2Markup#27] by https://github.com/zmitrok[@zmitrok]: Added a hook to preprocess a Swagger Model before it is converted.
+
 === Questions
 You can ask questions about Swagger2Markup in https://gitter.im/Swagger2Markup/swagger2markup[Gitter].
 

RELEASENOTES.adoc

@@ -63,4 +63,8 @@
 
 == Version 0.8.0
 * Enhancement #26 and #27: Added a pre-process hook to modify a Swagger Model before it is converted.
-* Bugfix #29: Tags are rendered twice
+* Bugfix #29: Tags are rendered twice
+
+=== Version 0.9.0
+* Updated swagger-parser from v1.0.8 to v1.0.13
+* Support for global responses and parameters

build.gradle

@@ -6,14 +6,14 @@ buildscript {
     dependencies {
         classpath 'org.asciidoctor:asciidoctor-gradle-plugin:1.5.2'
         classpath 'org.asciidoctor:asciidoctorj-pdf:1.5.0-alpha.8'
-        classpath 'io.spring.gradle:dependency-management-plugin:0.5.1.RELEASE'
+        classpath 'io.spring.gradle:dependency-management-plugin:0.5.3.RELEASE'
         classpath 'org.kt3k.gradle.plugin:coveralls-gradle-plugin:2.0.1'
         classpath 'org.asciidoctor:asciidoctorj:1.5.2'
         classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.2'
     }
 }
 description = 'swagger2markup Build'
-version = '0.8.0'
+version = '0.9.0'
 group = 'io.github.robwin'
 
 apply plugin: 'java'
@@ -54,7 +54,7 @@ dependencies {
 dependencyManagement {
     dependencies {
         dependency "io.github.robwin:markup-document-builder:0.1.4"
-        dependency "io.swagger:swagger-compat-spec-parser:1.0.8"
+        dependency "io.swagger:swagger-compat-spec-parser:1.0.13"
         dependency "commons-collections:commons-collections:3.2.1"
         dependency "commons-io:commons-io:2.4"
         dependency "junit:junit:4.11"

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

@@ -21,9 +21,7 @@ package io.github.robwin.swagger2markup;
 import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.github.robwin.markup.builder.MarkupLanguage;
-import io.github.robwin.swagger2markup.builder.document.DefinitionsDocument;
-import io.github.robwin.swagger2markup.builder.document.OverviewDocument;
-import io.github.robwin.swagger2markup.builder.document.PathsDocument;
+import io.github.robwin.swagger2markup.builder.document.*;
 import io.github.robwin.swagger2markup.utils.Consumer;
 import io.swagger.models.Swagger;
 import io.swagger.parser.SwaggerParser;
@@ -156,8 +154,8 @@ public class Swagger2MarkupConverter {
      * @return a the document as a String
      */
     private String buildDocuments() throws IOException {
-        return new OverviewDocument(swagger, markupLanguage).build().toString().concat(
-                new PathsDocument(swagger, markupLanguage, examplesFolderPath, schemasFolderPath).build().toString()
+        return new OverviewDocument(swagger, markupLanguage).build().toString()
+                .concat(new PathsDocument(swagger, markupLanguage, examplesFolderPath, schemasFolderPath).build().toString()
                 .concat(new DefinitionsDocument(swagger, markupLanguage, schemasFolderPath, schemasFolderPath, false, null).build().toString()));
     }
 

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

@@ -105,22 +105,23 @@ public class OverviewDocument extends MarkupDocument {
             this.markupDocBuilder.newLine();
         }
 
-        this.markupDocBuilder.sectionTitleLevel2(URI_SCHEME);
-        if(StringUtils.isNotBlank(swagger.getHost())){
-            this.markupDocBuilder.textLine(HOST + swagger.getHost());
-        }
-        if(StringUtils.isNotBlank(swagger.getBasePath())){
-            this.markupDocBuilder.textLine(BASE_PATH + swagger.getBasePath());
-        }
-        if(CollectionUtils.isNotEmpty(swagger.getSchemes())){
-            List<String> schemes = new ArrayList<>();
-            for(Scheme scheme : swagger.getSchemes()){
-                schemes.add(scheme.toString());
+        if(StringUtils.isNotBlank(swagger.getHost()) || StringUtils.isNotBlank(swagger.getBasePath()) || CollectionUtils.isNotEmpty(swagger.getSchemes())) {
+            this.markupDocBuilder.sectionTitleLevel2(URI_SCHEME);
+            if (StringUtils.isNotBlank(swagger.getHost())) {
+                this.markupDocBuilder.textLine(HOST + swagger.getHost());
             }
-            this.markupDocBuilder.textLine(SCHEMES + StringUtils.join(schemes, ", "));
-
+            if (StringUtils.isNotBlank(swagger.getBasePath())) {
+                this.markupDocBuilder.textLine(BASE_PATH + swagger.getBasePath());
+            }
+            if (CollectionUtils.isNotEmpty(swagger.getSchemes())) {
+                List<String> schemes = new ArrayList<>();
+                for (Scheme scheme : swagger.getSchemes()) {
+                    schemes.add(scheme.toString());
+                }
+                this.markupDocBuilder.textLine(SCHEMES + StringUtils.join(schemes, ", "));
+            }
+            this.markupDocBuilder.newLine();
         }
-        this.markupDocBuilder.newLine();
 
         if(CollectionUtils.isNotEmpty(swagger.getTags())){
             this.markupDocBuilder.sectionTitleLevel2(TAGS);

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

@@ -91,6 +91,44 @@ public class Swagger2MarkupConverterTest {
         assertThat(directories).hasSize(3).containsAll(asList("definitions.adoc", "overview.adoc", "paths.adoc"));
     }
 
+    @Test
+    public void testSwagger2AsciiDocConversionDoesNotContainUriScheme() throws IOException {
+        //Given
+        File file = new File(Swagger2MarkupConverterTest.class.getResource("/yaml/swagger_should_not_contain_uri_scheme.yaml").getFile());
+        File outputDirectory = new File("build/docs/asciidoc/generated");
+        FileUtils.deleteQuietly(outputDirectory);
+
+        //When
+        Swagger2MarkupConverter.from(file.getAbsolutePath()).build()
+                .intoFolder(outputDirectory.getAbsolutePath());
+
+        //Then
+        String[] directories = outputDirectory.list();
+        assertThat(directories).hasSize(3).containsAll(asList("definitions.adoc", "overview.adoc", "paths.adoc"));
+
+        assertThat(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "overview.adoc"))))
+                .doesNotContain("=== URI scheme");
+    }
+
+    @Test
+    public void testSwagger2AsciiDocConversionContainsUriScheme() throws IOException {
+        //Given
+        File file = new File(Swagger2MarkupConverterTest.class.getResource("/yaml/swagger_should_contain_uri_scheme.yaml").getFile());
+        File outputDirectory = new File("build/docs/asciidoc/generated");
+        FileUtils.deleteQuietly(outputDirectory);
+
+        //When
+        Swagger2MarkupConverter.from(file.getAbsolutePath()).build()
+                .intoFolder(outputDirectory.getAbsolutePath());
+
+        //Then
+        String[] directories = outputDirectory.list();
+        assertThat(directories).hasSize(3).containsAll(asList("definitions.adoc", "overview.adoc", "paths.adoc"));
+
+        assertThat(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "overview.adoc"))))
+                .contains("=== URI scheme");
+    }
+
     @Test
     public void testSwagger2MarkdownConversion() throws IOException {
         //Given

src/test/resources/json/swagger.json

@@ -134,13 +134,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "successful operation",
-                        "schema": {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/Pet"
-                            }
-                        }
+                        "$ref": "#/responses/FoundPets"
                     },
                     "400": {
                         "description": "Invalid status value"
@@ -183,13 +177,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "successful operation",
-                        "schema": {
-                            "type": "array",
-                            "items": {
-                                "$ref": "#/definitions/Pet"
-                            }
-                        }
+                        "$ref": "#/responses/FoundPets"
                     },
                     "400": {
                         "description": "Invalid tag value"
@@ -219,12 +207,7 @@
                 ],
                 "parameters": [
                     {
-                        "in": "path",
-                        "name": "petId",
-                        "description": "ID of pet that needs to be fetched",
-                        "required": true,
-                        "type": "integer",
-                        "format": "int64"
+                        "$ref": "#/parameters/petId"
                     }
                 ],
                 "responses": {
@@ -729,6 +712,27 @@
             }
         }
     },
+    "responses":{
+        "FoundPets": {
+            "description": "successful operation",
+            "schema": {
+                "type": "array",
+                "items": {
+                    "$ref": "#/definitions/Pet"
+                }
+            }
+        }
+    },
+    "parameters":{
+        "petId": {
+            "in": "path",
+            "name": "petId",
+            "description": "ID of the pet",
+            "required": true,
+            "type": "integer",
+            "format": "int64"
+        }
+    },
     "definitions": {
         "Identified": {
             "properties": {
@@ -767,6 +771,13 @@
                             "type": "integer",
                             "format": "int32",
                             "description": "User Status"
+                        },
+                        "pictures": {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "format": "byte"
+                            }
                         }
                     }
                 }

src/test/resources/yaml/swagger_should_contain_uri_scheme.yaml

@@ -0,0 +1,21 @@
+swagger: '2.0'
+info:
+  version: "0.0.0"
+  title: Test - Should contain URI scheme
+
+host: localhost
+
+schemes:
+  - http
+  - https
+
+basePath: /api
+
+paths:
+  /test:
+    get:
+      responses:
+        200:
+          description: OK
+          schema:
+            type: string

src/test/resources/yaml/swagger_should_not_contain_uri_scheme.yaml

@@ -0,0 +1,13 @@
+swagger: '2.0'
+info:
+  version: "0.0.0"
+  title: Test - Should not contain URI scheme
+ 
+paths:
+  /test:
+    get:
+      responses:
+        200:
+          description: OK
+          schema:
+            type: string