diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..b91399b7 --- /dev/null +++ b/README.adoc @@ -0,0 +1,43 @@ += swagger2AsciiDoc +This project is a Swagger to AsciiDoc converter. It takes an swagger.json or swagger.yaml as an input file +and generates an AsciiDoc file. +The primary goal of this project is to simplify the documentation of RESTful APIs. For example, you could +generate your AsciiDoc documentation using Spring Boot and swagger-springmvc as follows: + +[source,java] +---- +@RunWith(SpringJUnit4ClassRunner.class) +@SpringApplicationConfiguration(classes = SpringBootSwaggerConfig.class) +@IntegrationTest +@WebAppConfiguration +public class Swagger2AsciiDocTest { + + @Test + public void convertSwaggerToAsciiDoc() { + Swagger2AsciiDocConverter.newInstance("http://localhost:8080/api-docs", "src/docs/asciidoc/example.adoc").convertSwagger2AsciiDoc(); + } + +} +---- + +You can then generate HTML5 and PDF documentation via Asciidoctorj or even better via the asciidoctor-gradle-plugin. + +== Example swagger.json +image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/swagger_json.PNG + +== Example generated AsciiDoc file +image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc.PNG + +== Example generated HTML +image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc_html.PNG + +== License +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 [apache.org/licenses/LICENSE-2.0](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. \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index dd13ce78..00000000 --- a/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# swagger2AsciiDoc -This is a Swagger to AsciiDoc converter. It takes an swagger.json or swagger.yaml as an input file -and generates an AsciiDoc file. - -``` -Swagger2AsciiDocConverter.newInstance("/tmp/swagger.json", "/tmp/swagger.adoc").convertSwagger2AsciiDoc(); -``` - -Example swagger.json -![](https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/swagger_json.PNG) - -Example generated AsciiDoc file -![](https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc.PNG) - -Example generated HTML -![](https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc_html.PNG) diff --git a/build.gradle b/build.gradle index 350ba109..2ca9fc69 100644 --- a/build.gradle +++ b/build.gradle @@ -14,7 +14,7 @@ apply plugin: 'maven' apply plugin: 'org.asciidoctor.convert' version = '0.1.0' -group = 'io.swagger2AsciiDoc' +group = 'io.swagger2asciidoc' repositories { jcenter() @@ -23,6 +23,14 @@ repositories { maven {url "https://oss.sonatype.org/content/repositories/snapshots"} } +tasks.withType(JavaCompile) { + sourceCompatibility = "1.7" + targetCompatibility = "1.7" + options.deprecation = true + options.encoding = 'UTF-8' + options.compilerArgs << "-Xlint:unchecked" +} + dependencies { compile 'io.swagger:swagger-legacy-spec-parser:1.0.0-SNAPSHOT' compile 'commons-collections:commons-collections:3.2.1' diff --git a/src/main/java/io/swagger2asciidoc/Swagger2AsciiDocConverter.java b/src/main/java/io/swagger2asciidoc/Swagger2AsciiDocConverter.java index f419664c..31964437 100644 --- a/src/main/java/io/swagger2asciidoc/Swagger2AsciiDocConverter.java +++ b/src/main/java/io/swagger2asciidoc/Swagger2AsciiDocConverter.java @@ -16,6 +16,7 @@ import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Paths; import java.util.ArrayList; +import java.util.Arrays; import java.util.List; import java.util.Map; @@ -24,14 +25,15 @@ import java.util.Map; */ public class Swagger2AsciiDocConverter { private static final Logger logger = LoggerFactory.getLogger(Swagger2AsciiDocConverter.class); - public static final String VERSION = "Version: "; - public static final String SUMMARY = "Summary"; - public static final String DESCRIPTION = "Description"; - public static final String PARAMETERS = "Parameters"; - public static final String PRODUCES = "Produces"; - public static final String CONSUMES = "Consumes"; - public static final String RESPONSES = "Responses"; - public static final String DEFINITIONS = "Definitions"; + private static final String VERSION = "Version: "; + private static final String SUMMARY = "Summary"; + private static final String DESCRIPTION = "Description"; + private static final String PARAMETERS = "Parameters"; + private static final String PRODUCES = "Produces"; + private static final String CONSUMES = "Consumes"; + private static final String RESPONSES = "Responses"; + private static final String DEFINITIONS = "Definitions"; + private static final List IGNORED_DEFINITIONS = Arrays.asList("Void"); private final AsciiDocBuilder asciiDocBuilder; private final Swagger swagger; private final String asciiDocFileLocation; @@ -147,8 +149,6 @@ public class Swagger2AsciiDocConverter { } } - - private void responses(Operation operation) { Map responses = operation.getResponses(); if(MapUtils.isNotEmpty(responses)){ @@ -172,19 +172,21 @@ public class Swagger2AsciiDocConverter { asciiDocBuilder.sectionTitleLevel1(DEFINITIONS); for(Map.Entry definitionsEntry : definitions.entrySet()){ String definitionName = definitionsEntry.getKey(); - asciiDocBuilder.sectionTitleLevel2(definitionName); - Model response = definitionsEntry.getValue(); - Map properties = response.getProperties(); - List csvContent = new ArrayList<>(); - csvContent.add("Name,Type,Required"); - for(Map.Entry propertyEntry : properties.entrySet()){ - Property property = propertyEntry.getValue(); - StringBuilder rowBuilder = new StringBuilder(); - rowBuilder.append(propertyEntry.getKey()).append(","). - append(property.getType()).append(",").append(property.getRequired()); - csvContent.add(rowBuilder.toString()); + if(!IGNORED_DEFINITIONS.contains(definitionName)) { + asciiDocBuilder.sectionTitleLevel2(definitionName); + Model model = definitionsEntry.getValue(); + Map properties = model.getProperties(); + List csvContent = new ArrayList<>(); + csvContent.add("Name,Type,Required"); + for (Map.Entry propertyEntry : properties.entrySet()) { + Property property = propertyEntry.getValue(); + StringBuilder rowBuilder = new StringBuilder(); + rowBuilder.append(propertyEntry.getKey()).append(","). + append(property.getType()).append(",").append(property.getRequired()); + csvContent.add(rowBuilder.toString()); + } + asciiDocBuilder.tableWithHeaderRow(csvContent); } - asciiDocBuilder.tableWithHeaderRow(csvContent); } } } diff --git a/src/test/java/io/swagger2asciidoc/Swagger2AsciiDocConverterTest.java b/src/test/java/io/swagger2asciidoc/Swagger2AsciiDocConverterTest.java index 20a664ab..36aad0dd 100644 --- a/src/test/java/io/swagger2asciidoc/Swagger2AsciiDocConverterTest.java +++ b/src/test/java/io/swagger2asciidoc/Swagger2AsciiDocConverterTest.java @@ -5,11 +5,7 @@ import org.junit.Test; import java.io.File; /** - * Project: swagger2AsciiDoc - * Copyright: Deutsche Telekom AG - * - * @author Robert Winkler - * @since 2.0.0 + * @author Robert Winkler */ public class Swagger2AsciiDocConverterTest {