mindol1004/swagger2markup
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Robert Winkler
2015-06-23 09:24:15 +02:00
parent 675dd762a8
commit 90880a00f3
6 changed files with 54 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
README.adoc
View File

@@ -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

3
RELEASENOTES.adoc
View File

@@ -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

2
build.gradle
View File

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

23
src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java
View File

@@ -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,7 +138,7 @@ public class Swagger2MarkupConverter {
}
/**
* 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
@@ -145,11 +146,11 @@ public class Swagger2MarkupConverter {
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 class Swagger2MarkupConverter {
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 class Swagger2MarkupConverter {
}
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 class Swagger2MarkupConverter {
}
/**
* 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;
}

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

@@ -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 class DefinitionsDocument extends MarkupDocument {
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 @@ public class DefinitionsDocument extends MarkupDocument {
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);

25
src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java
View File

@@ -103,14 +103,14 @@ public class Swagger2MarkupConverterTest {
}
@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 class Swagger2MarkupConverterTest {
.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 {