From 63ca190a329996d7db8f7ee4d84bb1e7a9845532 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Thu, 4 Feb 2016 18:51:22 +0100 Subject: [PATCH 1/3] fixed #51 : Support for separated operations files --- .../Swagger2MarkupConverter.java | 16 +- .../builder/document/DefinitionsDocument.java | 48 ++--- .../builder/document/PathsDocument.java | 165 +++++++++++------- .../config/Swagger2MarkupConfig.java | 9 +- .../Swagger2MarkupConverterTest.java | 29 +-- 5 files changed, 170 insertions(+), 97 deletions(-) diff --git a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java index c4f84fa5..d2421f1b 100644 --- a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java +++ b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java @@ -119,7 +119,7 @@ public class Swagger2MarkupConverter { */ private void buildDocuments(String directory) throws IOException { new OverviewDocument(swagger2MarkupConfig).build().writeToFile(directory, OVERVIEW_DOCUMENT, StandardCharsets.UTF_8); - new PathsDocument(swagger2MarkupConfig).build().writeToFile(directory, PATHS_DOCUMENT, StandardCharsets.UTF_8); + new PathsDocument(swagger2MarkupConfig, directory).build().writeToFile(directory, PATHS_DOCUMENT, StandardCharsets.UTF_8); new DefinitionsDocument(swagger2MarkupConfig, directory).build().writeToFile(directory, DEFINITIONS_DOCUMENT, StandardCharsets.UTF_8); } @@ -130,7 +130,7 @@ public class Swagger2MarkupConverter { */ private String buildDocuments() { return new OverviewDocument(swagger2MarkupConfig).build().toString() - .concat(new PathsDocument(swagger2MarkupConfig).build().toString() + .concat(new PathsDocument(swagger2MarkupConfig, null).build().toString() .concat(new DefinitionsDocument(swagger2MarkupConfig, null).build().toString())); } @@ -141,6 +141,7 @@ public class Swagger2MarkupConverter { private String schemasFolderPath; private String descriptionsFolderPath; private boolean separatedDefinitions; + private boolean separatedOperations; private GroupBy pathsGroupedBy = GroupBy.AS_IS; private OrderBy definitionsOrderedBy = OrderBy.NATURAL; private MarkupLanguage markupLanguage = MarkupLanguage.ASCIIDOC; @@ -170,7 +171,7 @@ public class Swagger2MarkupConverter { public Swagger2MarkupConverter build(){ return new Swagger2MarkupConverter(new Swagger2MarkupConfig(swagger, markupLanguage, examplesFolderPath, - schemasFolderPath, descriptionsFolderPath, separatedDefinitions, pathsGroupedBy, definitionsOrderedBy, + schemasFolderPath, descriptionsFolderPath, separatedDefinitions, separatedOperations, pathsGroupedBy, definitionsOrderedBy, outputLanguage, inlineSchemaDepthLevel)); } @@ -205,6 +206,15 @@ public class Swagger2MarkupConverter { return this; } + /** + * In addition to the paths file, also create separate path files for each path. + * @return the Swagger2MarkupConverter.Builder + */ + public Builder withSeparatedOperations() { + this.separatedOperations = true; + return this; + } + /** * Include examples into the Paths document * diff --git a/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java b/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java index 8ac42a17..d1956f26 100644 --- a/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java +++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java @@ -58,6 +58,7 @@ public class DefinitionsDocument extends MarkupDocument { private static final String JSON = "json"; private static final String XML = "xml"; private static final String DESCRIPTION_FOLDER_NAME = "definitions"; + private static final String SEPARATED_DEFINITIONS_FOLDER_NAME = "definitions"; private static final String DESCRIPTION_FILE_NAME = "description"; private boolean schemasEnabled; private String schemasFolderPath; @@ -121,7 +122,7 @@ public class DefinitionsDocument extends MarkupDocument { @Override public MarkupDocument build(){ - definitions(swagger.getDefinitions(), this.markupDocBuilder); + definitions(swagger.getDefinitions()); return this; } @@ -129,11 +130,10 @@ public class DefinitionsDocument extends MarkupDocument { * Builds the Swagger definitions. * * @param definitions the Swagger definitions - * @param docBuilder the doc builder to use for output */ - private void definitions(Map definitions, MarkupDocBuilder docBuilder){ + private void definitions(Map definitions){ if(MapUtils.isNotEmpty(definitions)){ - docBuilder.sectionTitleLevel1(DEFINITIONS); + this.markupDocBuilder.sectionTitleLevel1(DEFINITIONS); Set definitionNames; if(definitionsOrderedBy.equals(OrderBy.AS_IS)){ definitionNames = definitions.keySet(); @@ -144,23 +144,7 @@ public class DefinitionsDocument extends MarkupDocument { Model model = definitions.get(definitionName); if(isNotBlank(definitionName)) { if (checkThatDefinitionIsNotInIgnoreList(definitionName)) { - definition(definitions, definitionName, model, docBuilder); - definitionSchema(definitionName, docBuilder); - if (separatedDefinitionsEnabled) { - MarkupDocBuilder defDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage); - definition(definitions, definitionName, model, defDocBuilder); - definitionSchema(definitionName, defDocBuilder); - try { - defDocBuilder.writeToFile(outputDirectory, definitionName.toLowerCase(), StandardCharsets.UTF_8); - } catch (IOException e) { - if (logger.isWarnEnabled()) { - logger.warn(String.format("Failed to write definition file: %s", definitionName), e); - } - } - if (logger.isInfoEnabled()) { - logger.info("Separate definition file produced: {}", definitionName); - } - } + processDefinition(definitions, definitionName, model); if (logger.isInfoEnabled()) { logger.info("Definition processed: {}", definitionName); } @@ -174,6 +158,27 @@ public class DefinitionsDocument extends MarkupDocument { } } + private void processDefinition(Map definitions, String definitionName, Model model) { + + definition(definitions, definitionName, model, this.markupDocBuilder); + + if (separatedDefinitionsEnabled) { + MarkupDocBuilder defDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage); + definition(definitions, definitionName, model, defDocBuilder); + String definitionFileName = definitionName.toLowerCase(); + try { + defDocBuilder.writeToFile(Paths.get(outputDirectory, SEPARATED_DEFINITIONS_FOLDER_NAME).toString(), definitionFileName, StandardCharsets.UTF_8); + } catch (IOException e) { + if (logger.isWarnEnabled()) { + logger.warn(String.format("Failed to write definition file: %s", definitionFileName), e); + } + } + if (logger.isInfoEnabled()) { + logger.info("Separate definition file produced: {}", definitionFileName); + } + } + } + /** * Checks that the definition is not in the list of ignored definitions. * @@ -195,6 +200,7 @@ public class DefinitionsDocument extends MarkupDocument { docBuilder.sectionTitleLevel2(definitionName); descriptionSection(definitionName, model, docBuilder); propertiesSection(definitions, definitionName, model, docBuilder); + definitionSchema(definitionName, docBuilder); } private class DefinitionPropertyDescriptor extends PropertyDescriptor { diff --git a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java index 6784676a..fa03d93a 100644 --- a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java +++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java @@ -20,6 +20,8 @@ package io.github.robwin.swagger2markup.builder.document; import com.google.common.base.Optional; import com.google.common.collect.Multimap; +import io.github.robwin.markup.builder.MarkupDocBuilder; +import io.github.robwin.markup.builder.MarkupDocBuilders; import io.github.robwin.swagger2markup.GroupBy; import io.github.robwin.swagger2markup.config.Swagger2MarkupConfig; import io.github.robwin.swagger2markup.type.ObjectType; @@ -34,6 +36,7 @@ import io.swagger.models.properties.Property; import org.apache.commons.collections.CollectionUtils; import org.apache.commons.collections.MapUtils; import org.apache.commons.io.FileUtils; +import org.apache.commons.lang3.Validate; import org.apache.commons.lang3.text.WordUtils; import org.apache.commons.lang3.tuple.Pair; @@ -42,6 +45,7 @@ import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Paths; import java.util.*; +import java.util.regex.Pattern; import static io.github.robwin.swagger2markup.utils.TagUtils.*; import static org.apache.commons.lang3.StringUtils.defaultString; @@ -66,9 +70,10 @@ public class PathsDocument extends MarkupDocument { private static final String RESPONSE_EXAMPLE_FILE_NAME = "http-response"; private static final String CURL_EXAMPLE_FILE_NAME = "curl-request"; private static final String DESCRIPTION_FOLDER_NAME = "paths"; + private static final String SEPARATED_OPERATIONS_FOLDER_NAME = "operations"; private static final String DESCRIPTION_FILE_NAME = "description"; private final String PARAMETER; - + private static final Pattern FILENAME_FORBIDDEN_PATTERN = Pattern.compile("[^0-9A-Za-z-_]+"); private boolean examplesEnabled; private String examplesFolderPath; @@ -76,8 +81,10 @@ public class PathsDocument extends MarkupDocument { private String descriptionsFolderPath; private final GroupBy pathsGroupedBy; private final int inlineSchemaDepthLevel; + private boolean separatedOperationsEnabled; + private String outputDirectory; - public PathsDocument(Swagger2MarkupConfig swagger2MarkupConfig){ + public PathsDocument(Swagger2MarkupConfig swagger2MarkupConfig, String outputDirectory){ super(swagger2MarkupConfig); ResourceBundle labels = ResourceBundle.getBundle("lang/labels", @@ -103,6 +110,7 @@ public class PathsDocument extends MarkupDocument { this.handWrittenDescriptionsEnabled = true; this.descriptionsFolderPath = swagger2MarkupConfig.getDescriptionsFolderPath() + "/" + DESCRIPTION_FOLDER_NAME; } + if(examplesEnabled){ if (logger.isDebugEnabled()) { logger.debug("Include examples is enabled."); @@ -121,6 +129,19 @@ public class PathsDocument extends MarkupDocument { logger.debug("Include hand-written descriptions is disabled."); } } + + this.separatedOperationsEnabled = swagger2MarkupConfig.isSeparatedOperations(); + if(this.separatedOperationsEnabled){ + if (logger.isDebugEnabled()) { + logger.debug("Create separated operation files is enabled."); + } + Validate.notEmpty(outputDirectory, "Output directory is required for separated operation files!"); + }else{ + if (logger.isDebugEnabled()) { + logger.debug("Create separated operation files is disabled."); + } + } + this.outputDirectory = outputDirectory; } /** @@ -173,26 +194,50 @@ public class PathsDocument extends MarkupDocument { private void createPathSections(String pathUrl, Path path){ for(Map.Entry operationEntry : path.getOperationMap().entrySet()){ String methodAndPath = operationEntry.getKey() + " " + pathUrl; - path(methodAndPath, operationEntry.getValue()); + processPath(methodAndPath, operationEntry.getValue()); + } + } + + private void processPath(String methodAndPath, Operation operation) { + + path(methodAndPath, operation, this.markupDocBuilder); + + if (separatedOperationsEnabled) { + MarkupDocBuilder pathDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage); + path(methodAndPath, operation, pathDocBuilder); + String operationFileName = operation.getOperationId(); + if (operationFileName == null) + operationFileName = methodAndPath; + operationFileName = FILENAME_FORBIDDEN_PATTERN.matcher(operationFileName).replaceAll("_").toLowerCase(); + try { + pathDocBuilder.writeToFile(Paths.get(outputDirectory, SEPARATED_OPERATIONS_FOLDER_NAME).toString(), operationFileName, StandardCharsets.UTF_8); + } catch (IOException e) { + if (logger.isWarnEnabled()) { + logger.warn(String.format("Failed to write operation file: %s", operationFileName), e); + } + } + if (logger.isInfoEnabled()) { + logger.info("Separate operation file produced: {}", operationFileName); + } } } /** - * Builds a path. + * Builds an operation. * * @param methodAndPath the Method of the operation and the URL of the path * @param operation the Swagger Operation */ - private void path(String methodAndPath, Operation operation) { + private void path(String methodAndPath, Operation operation, MarkupDocBuilder docBuilder) { if(operation != null){ - pathTitle(methodAndPath, operation); - descriptionSection(operation); - inlineDefinitions(parametersSection(operation), inlineSchemaDepthLevel); - inlineDefinitions(responsesSection(operation), inlineSchemaDepthLevel); - consumesSection(operation); - producesSection(operation); - tagsSection(operation); - examplesSection(operation); + pathTitle(methodAndPath, operation, docBuilder); + descriptionSection(operation, docBuilder); + inlineDefinitions(parametersSection(operation, docBuilder), inlineSchemaDepthLevel, docBuilder); + inlineDefinitions(responsesSection(operation, docBuilder), inlineSchemaDepthLevel, docBuilder); + consumesSection(operation, docBuilder); + producesSection(operation, docBuilder); + tagsSection(operation, docBuilder); + examplesSection(operation, docBuilder); } } @@ -203,15 +248,15 @@ public class PathsDocument extends MarkupDocument { * @param methodAndPath the Method of the operation and the URL of the path * @param operation the Swagger Operation */ - private void pathTitle(String methodAndPath, Operation operation) { + private void pathTitle(String methodAndPath, Operation operation, MarkupDocBuilder docBuilder) { String summary = operation.getSummary(); String title; if(isNotBlank(summary)) { title = summary; - addPathTitle(title); - this.markupDocBuilder.listing(methodAndPath); + addPathTitle(title, docBuilder); + docBuilder.listing(methodAndPath); }else{ - addPathTitle(methodAndPath); + addPathTitle(methodAndPath, docBuilder); } if (logger.isInfoEnabled()) { logger.info("Path processed: {}", methodAndPath); @@ -223,11 +268,11 @@ public class PathsDocument extends MarkupDocument { * * @param title the path title */ - private void addPathTitle(String title) { + private void addPathTitle(String title, MarkupDocBuilder docBuilder) { if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel2(title); + docBuilder.sectionTitleLevel2(title); }else{ - this.markupDocBuilder.sectionTitleLevel3(title); + docBuilder.sectionTitleLevel3(title); } } @@ -236,11 +281,11 @@ public class PathsDocument extends MarkupDocument { * * @param title the path title */ - private void addPathSectionTitle(String title) { + private void addPathSectionTitle(String title, MarkupDocBuilder docBuilder) { if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(title); + docBuilder.sectionTitleLevel3(title); }else{ - this.markupDocBuilder.sectionTitleLevel4(title); + docBuilder.sectionTitleLevel4(title); } } @@ -249,39 +294,39 @@ public class PathsDocument extends MarkupDocument { * * @param operation the Swagger Operation */ - private void descriptionSection(Operation operation) { + private void descriptionSection(Operation operation, MarkupDocBuilder docBuilder) { if(handWrittenDescriptionsEnabled){ String summary = operation.getSummary(); if(isNotBlank(summary)) { String operationFolder = summary.replace(".", "").replace(" ", "_").toLowerCase(); Optional description = handWrittenPathDescription(operationFolder, DESCRIPTION_FILE_NAME); if(description.isPresent()){ - pathDescription(description.get()); + pathDescription(description.get(), docBuilder); }else{ if (logger.isInfoEnabled()) { logger.info("Hand-written description cannot be read. Trying to use description from Swagger source."); } - pathDescription(operation.getDescription()); + pathDescription(operation.getDescription(), docBuilder); } }else{ if (logger.isInfoEnabled()) { logger.info("Hand-written description cannot be read, because summary of operation is empty. Trying to use description from Swagger source."); } - pathDescription(operation.getDescription()); + pathDescription(operation.getDescription(), docBuilder); } }else { - pathDescription(operation.getDescription()); + pathDescription(operation.getDescription(), docBuilder); } } - private void pathDescription(String description) { + private void pathDescription(String description, MarkupDocBuilder docBuilder) { if (isNotBlank(description)) { - addPathSectionTitle(DESCRIPTION); - this.markupDocBuilder.paragraph(description); + addPathSectionTitle(DESCRIPTION, docBuilder); + docBuilder.paragraph(description); } } - private List parametersSection(Operation operation) { + private List parametersSection(Operation operation, MarkupDocBuilder docBuilder) { List parameters = operation.getParameters(); List localDefinitions = new ArrayList<>(); if(CollectionUtils.isNotEmpty(parameters)){ @@ -304,14 +349,14 @@ public class PathsDocument extends MarkupDocument { List content = Arrays.asList( parameterType, parameter.getName(), - parameterDescription(operation, parameter), + parameterDescription(operation, parameter, docBuilder), Boolean.toString(parameter.getRequired()), type.displaySchema(markupLanguage), ParameterUtils.getDefaultValue(parameter)); cells.add(content); } - addPathSectionTitle(PARAMETERS); - MarkupDocBuilderUtils.tableWithHeaderRow(Arrays.asList(1, 1, 6, 1, 1, 1), cells, this.markupDocBuilder); + addPathSectionTitle(PARAMETERS, docBuilder); + MarkupDocBuilderUtils.tableWithHeaderRow(Arrays.asList(1, 1, 6, 1, 1, 1), cells, docBuilder); } return localDefinitions; @@ -326,7 +371,7 @@ public class PathsDocument extends MarkupDocument { * @param parameter the Swagger Parameter * @return the description of a parameter. */ - private String parameterDescription(Operation operation, Parameter parameter){ + private String parameterDescription(Operation operation, Parameter parameter, MarkupDocBuilder docBuilder){ if(handWrittenDescriptionsEnabled){ String summary = operation.getSummary(); String operationFolder = summary.replace(".", "").replace(" ", "_").toLowerCase(); @@ -353,29 +398,29 @@ public class PathsDocument extends MarkupDocument { } } - private void consumesSection(Operation operation) { + private void consumesSection(Operation operation, MarkupDocBuilder docBuilder) { List consumes = operation.getConsumes(); if(CollectionUtils.isNotEmpty(consumes)){ - addPathSectionTitle(CONSUMES); - this.markupDocBuilder.unorderedList(consumes); + addPathSectionTitle(CONSUMES, docBuilder); + docBuilder.unorderedList(consumes); } } - private void producesSection(Operation operation) { + private void producesSection(Operation operation, MarkupDocBuilder docBuilder) { List produces = operation.getProduces(); if(CollectionUtils.isNotEmpty(produces)){ - addPathSectionTitle(PRODUCES); - this.markupDocBuilder.unorderedList(produces); + addPathSectionTitle(PRODUCES, docBuilder); + docBuilder.unorderedList(produces); } } - private void tagsSection(Operation operation) { + private void tagsSection(Operation operation, MarkupDocBuilder docBuilder) { if(pathsGroupedBy.equals(GroupBy.AS_IS)) { List tags = operation.getTags(); if (CollectionUtils.isNotEmpty(tags)) { - addPathSectionTitle(TAGS); - this.markupDocBuilder.unorderedList(tags); + addPathSectionTitle(TAGS, docBuilder); + docBuilder.unorderedList(tags); } } } @@ -387,26 +432,26 @@ public class PathsDocument extends MarkupDocument { * * @param operation the Swagger Operation */ - private void examplesSection(Operation operation) { + private void examplesSection(Operation operation, MarkupDocBuilder docBuilder) { if(examplesEnabled){ String summary = operation.getSummary(); if(isNotBlank(summary)) { String exampleFolder = summary.replace(".", "").replace(" ", "_").toLowerCase(); Optional curlExample = example(exampleFolder, CURL_EXAMPLE_FILE_NAME); if(curlExample.isPresent()){ - addPathSectionTitle(EXAMPLE_CURL); - this.markupDocBuilder.paragraph(curlExample.get()); + addPathSectionTitle(EXAMPLE_CURL, docBuilder); + docBuilder.paragraph(curlExample.get()); } Optional requestExample = example(exampleFolder, REQUEST_EXAMPLE_FILE_NAME); if(requestExample.isPresent()){ - addPathSectionTitle(EXAMPLE_REQUEST); - this.markupDocBuilder.paragraph(requestExample.get()); + addPathSectionTitle(EXAMPLE_REQUEST, docBuilder); + docBuilder.paragraph(requestExample.get()); } Optional responseExample = example(exampleFolder, RESPONSE_EXAMPLE_FILE_NAME); if(responseExample.isPresent()){ - addPathSectionTitle(EXAMPLE_RESPONSE); - this.markupDocBuilder.paragraph(responseExample.get()); + addPathSectionTitle(EXAMPLE_RESPONSE, docBuilder); + docBuilder.paragraph(responseExample.get()); } }else{ if (logger.isWarnEnabled()) { @@ -482,7 +527,7 @@ public class PathsDocument extends MarkupDocument { return Optional.absent(); } - private List responsesSection(Operation operation) { + private List responsesSection(Operation operation, MarkupDocBuilder docBuilder) { Map responses = operation.getResponses(); List localDefinitions = new ArrayList<>(); if(MapUtils.isNotEmpty(responses)){ @@ -506,23 +551,23 @@ public class PathsDocument extends MarkupDocument { cells.add(Arrays.asList(entry.getKey(), response.getDescription(), NO_CONTENT)); } } - addPathSectionTitle(RESPONSES); - MarkupDocBuilderUtils.tableWithHeaderRow(Arrays.asList(1, 6, 1), cells, this.markupDocBuilder); + addPathSectionTitle(RESPONSES, docBuilder); + MarkupDocBuilderUtils.tableWithHeaderRow(Arrays.asList(1, 6, 1), cells, docBuilder); } return localDefinitions; } - private void inlineDefinitions(List definitions, int depth) { + private void inlineDefinitions(List definitions, int depth, MarkupDocBuilder docBuilder) { if(CollectionUtils.isNotEmpty(definitions)){ for (Type definition: definitions) { if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - MarkupDocBuilderUtils.sectionTitleLevel(4, definition.getName(), definition.getUniqueName(), this.markupDocBuilder); + MarkupDocBuilderUtils.sectionTitleLevel(4, definition.getName(), definition.getUniqueName(), docBuilder); }else{ - MarkupDocBuilderUtils.sectionTitleLevel(5, definition.getName(), definition.getUniqueName(), this.markupDocBuilder); + MarkupDocBuilderUtils.sectionTitleLevel(5, definition.getName(), definition.getUniqueName(), docBuilder); } - List localDefinitions = typeProperties(definition, depth, new PropertyDescriptor(definition), this.markupDocBuilder); + List localDefinitions = typeProperties(definition, depth, new PropertyDescriptor(definition), docBuilder); for (Type localDefinition : localDefinitions) - inlineDefinitions(Collections.singletonList(localDefinition), depth - 1); + inlineDefinitions(Collections.singletonList(localDefinition), depth - 1, docBuilder); } } diff --git a/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java b/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java index a212c23d..f2a44a00 100644 --- a/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java +++ b/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java @@ -32,6 +32,7 @@ public class Swagger2MarkupConfig { private final String schemasFolderPath; private final String descriptionsFolderPath; private final boolean separatedDefinitions; + private final boolean separatedOperations; private final GroupBy pathsGroupedBy; private final OrderBy definitionsOrderedBy; private final Language outputLanguage; @@ -44,13 +45,14 @@ public class Swagger2MarkupConfig { * @param schemasFolderPath the path to the folder where the schema documents reside * @param descriptionsFolderPath the path to the folder where the description documents reside * @param separatedDefinitions specified if in addition to the definitions file, also separate definition files for each model definition should be created + * @param separatedOperations specified if in addition to the operations file, also separate path files for each operation should be created * @param pathsGroupedBy specifies if the paths should be grouped by tags or stay as-is * @param definitionsOrderedBy specifies if the definitions should be ordered by natural ordering or stay as-is * @param outputLanguage specifies language of labels in output files * @param inlineSchemaDepthLevel specifies the max depth for inline object schema display (0 = no inline schemas) */ public Swagger2MarkupConfig(Swagger swagger, MarkupLanguage markupLanguage, String examplesFolderPath, - String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions, + String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions, boolean separatedOperations, GroupBy pathsGroupedBy, OrderBy definitionsOrderedBy, Language outputLanguage, int inlineSchemaDepthLevel) { this.swagger = swagger; @@ -59,6 +61,7 @@ public class Swagger2MarkupConfig { this.schemasFolderPath = schemasFolderPath; this.descriptionsFolderPath = descriptionsFolderPath; this.separatedDefinitions = separatedDefinitions; + this.separatedOperations = separatedOperations; this.pathsGroupedBy = pathsGroupedBy; this.definitionsOrderedBy = definitionsOrderedBy; this.outputLanguage = outputLanguage; @@ -89,6 +92,10 @@ public class Swagger2MarkupConfig { return separatedDefinitions; } + public boolean isSeparatedOperations() { + return separatedOperations; + } + public GroupBy getPathsGroupedBy() { return pathsGroupedBy; } diff --git a/src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java b/src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java index ed2144e5..7260e915 100644 --- a/src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java +++ b/src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java @@ -248,11 +248,11 @@ public class Swagger2MarkupConverterTest { //Then String[] directories = outputDirectory.list(); - assertThat(directories).hasSize(9).containsAll( - asList("definitions.adoc", "overview.adoc", "paths.adoc", "identified.adoc", - "user.adoc", "category.adoc", "pet.adoc", "tag.adoc", "order.adoc")); + assertThat(directories).hasSize(4).containsAll( + asList("definitions", "definitions.adoc", "overview.adoc", "paths.adoc")); + File definitionsDirectory = new File(outputDirectory, "definitions"); assertThat(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "definitions.adoc")))) - .contains(new String(Files.readAllBytes(Paths.get(outputDirectory + File.separator + "user.adoc")))); + .contains(new String(Files.readAllBytes(Paths.get(definitionsDirectory + File.separator + "user.adoc")))); } @Test @@ -269,11 +269,16 @@ public class Swagger2MarkupConverterTest { //Then String[] directories = outputDirectory.list(); - assertThat(directories).hasSize(9).containsAll( - asList("definitions.md", "overview.md", "paths.md", "identified.md", - "user.md", "category.md", "pet.md", "tag.md", "order.md")); + assertThat(directories).hasSize(4).containsAll( + asList("definitions", "definitions.md", "overview.md", "paths.md")); + + File definitionsDirectory = new File(outputDirectory, "definitions"); + String[] definitions = definitionsDirectory.list(); + assertThat(definitions).hasSize(6).containsAll( + asList("identified.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")))); + .contains(new String(Files.readAllBytes(Paths.get(definitionsDirectory + File.separator + "user.md")))); } @Test @@ -290,9 +295,8 @@ public class Swagger2MarkupConverterTest { // Then String[] directories = outputDirectory.list(); - assertThat(directories).hasSize(9).containsAll( - asList("definitions.md", "overview.md", "paths.md", "identified.md", - "user.md", "category.md", "pet.md", "tag.md", "order.md")); + assertThat(directories).hasSize(4).containsAll( + asList("definitions", "definitions.md", "overview.md", "paths.md")); verifyMarkdownContainsFieldsInTables( outputDirectory + File.separator + "definitions.md", ImmutableMap.>builder() @@ -300,8 +304,9 @@ public class Swagger2MarkupConverterTest { .put("User", ImmutableSet.of("id", "username", "firstName", "lastName", "email", "password", "phone", "userStatus")) .build()); + File definitionsDirectory = new File(outputDirectory, "definitions"); verifyMarkdownContainsFieldsInTables( - outputDirectory + File.separator + "user.md", + definitionsDirectory + File.separator + "user.md", ImmutableMap.>builder() .put("User", ImmutableSet.of("id", "username", "firstName", "lastName", "email", "password", "phone", "userStatus")) From 8178bf1380d4398b65d3f0ea8ac96e882757a1b9 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Fri, 5 Feb 2016 00:10:45 +0100 Subject: [PATCH 2/3] renamed withSeparatedOperations to withSeparatedPaths along with all related resources --- .../Swagger2MarkupConverter.java | 8 ++--- .../builder/document/DefinitionsDocument.java | 2 +- .../builder/document/PathsDocument.java | 30 +++++++++---------- .../config/Swagger2MarkupConfig.java | 12 ++++---- 4 files changed, 26 insertions(+), 26 deletions(-) diff --git a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java index d2421f1b..3cf9c264 100644 --- a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java +++ b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java @@ -141,7 +141,7 @@ public class Swagger2MarkupConverter { private String schemasFolderPath; private String descriptionsFolderPath; private boolean separatedDefinitions; - private boolean separatedOperations; + private boolean separatedPaths; private GroupBy pathsGroupedBy = GroupBy.AS_IS; private OrderBy definitionsOrderedBy = OrderBy.NATURAL; private MarkupLanguage markupLanguage = MarkupLanguage.ASCIIDOC; @@ -171,7 +171,7 @@ public class Swagger2MarkupConverter { public Swagger2MarkupConverter build(){ return new Swagger2MarkupConverter(new Swagger2MarkupConfig(swagger, markupLanguage, examplesFolderPath, - schemasFolderPath, descriptionsFolderPath, separatedDefinitions, separatedOperations, pathsGroupedBy, definitionsOrderedBy, + schemasFolderPath, descriptionsFolderPath, separatedDefinitions, separatedPaths, pathsGroupedBy, definitionsOrderedBy, outputLanguage, inlineSchemaDepthLevel)); } @@ -210,8 +210,8 @@ public class Swagger2MarkupConverter { * In addition to the paths file, also create separate path files for each path. * @return the Swagger2MarkupConverter.Builder */ - public Builder withSeparatedOperations() { - this.separatedOperations = true; + public Builder withSeparatedPaths() { + this.separatedPaths = true; return this; } diff --git a/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java b/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java index d1956f26..4a73d4ff 100644 --- a/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java +++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java @@ -58,8 +58,8 @@ public class DefinitionsDocument extends MarkupDocument { private static final String JSON = "json"; private static final String XML = "xml"; private static final String DESCRIPTION_FOLDER_NAME = "definitions"; - private static final String SEPARATED_DEFINITIONS_FOLDER_NAME = "definitions"; private static final String DESCRIPTION_FILE_NAME = "description"; + private static final String SEPARATED_DEFINITIONS_FOLDER_NAME = "definitions"; private boolean schemasEnabled; private String schemasFolderPath; private boolean handWrittenDescriptionsEnabled; diff --git a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java index fa03d93a..1804470f 100644 --- a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java +++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java @@ -70,8 +70,8 @@ public class PathsDocument extends MarkupDocument { private static final String RESPONSE_EXAMPLE_FILE_NAME = "http-response"; private static final String CURL_EXAMPLE_FILE_NAME = "curl-request"; private static final String DESCRIPTION_FOLDER_NAME = "paths"; - private static final String SEPARATED_OPERATIONS_FOLDER_NAME = "operations"; private static final String DESCRIPTION_FILE_NAME = "description"; + private static final String SEPARATED_PATHS_FOLDER_NAME = "paths"; private final String PARAMETER; private static final Pattern FILENAME_FORBIDDEN_PATTERN = Pattern.compile("[^0-9A-Za-z-_]+"); @@ -81,7 +81,7 @@ public class PathsDocument extends MarkupDocument { private String descriptionsFolderPath; private final GroupBy pathsGroupedBy; private final int inlineSchemaDepthLevel; - private boolean separatedOperationsEnabled; + private boolean separatedPathsEnabled; private String outputDirectory; public PathsDocument(Swagger2MarkupConfig swagger2MarkupConfig, String outputDirectory){ @@ -130,15 +130,15 @@ public class PathsDocument extends MarkupDocument { } } - this.separatedOperationsEnabled = swagger2MarkupConfig.isSeparatedOperations(); - if(this.separatedOperationsEnabled){ + this.separatedPathsEnabled = swagger2MarkupConfig.isSeparatedPaths(); + if(this.separatedPathsEnabled){ if (logger.isDebugEnabled()) { - logger.debug("Create separated operation files is enabled."); + logger.debug("Create separated path files is enabled."); } - Validate.notEmpty(outputDirectory, "Output directory is required for separated operation files!"); + Validate.notEmpty(outputDirectory, "Output directory is required for separated path files!"); }else{ if (logger.isDebugEnabled()) { - logger.debug("Create separated operation files is disabled."); + logger.debug("Create separated path files is disabled."); } } this.outputDirectory = outputDirectory; @@ -202,22 +202,22 @@ public class PathsDocument extends MarkupDocument { path(methodAndPath, operation, this.markupDocBuilder); - if (separatedOperationsEnabled) { + if (separatedPathsEnabled) { MarkupDocBuilder pathDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage); path(methodAndPath, operation, pathDocBuilder); - String operationFileName = operation.getOperationId(); - if (operationFileName == null) - operationFileName = methodAndPath; - operationFileName = FILENAME_FORBIDDEN_PATTERN.matcher(operationFileName).replaceAll("_").toLowerCase(); + String pathFileName = operation.getOperationId(); + if (pathFileName == null) + pathFileName = methodAndPath; + pathFileName = FILENAME_FORBIDDEN_PATTERN.matcher(pathFileName).replaceAll("_").toLowerCase(); try { - pathDocBuilder.writeToFile(Paths.get(outputDirectory, SEPARATED_OPERATIONS_FOLDER_NAME).toString(), operationFileName, StandardCharsets.UTF_8); + pathDocBuilder.writeToFile(Paths.get(outputDirectory, SEPARATED_PATHS_FOLDER_NAME).toString(), pathFileName, StandardCharsets.UTF_8); } catch (IOException e) { if (logger.isWarnEnabled()) { - logger.warn(String.format("Failed to write operation file: %s", operationFileName), e); + logger.warn(String.format("Failed to write path file: %s", pathFileName), e); } } if (logger.isInfoEnabled()) { - logger.info("Separate operation file produced: {}", operationFileName); + logger.info("Separate path file produced: {}", pathFileName); } } } diff --git a/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java b/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java index f2a44a00..3858c6f0 100644 --- a/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java +++ b/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java @@ -32,7 +32,7 @@ public class Swagger2MarkupConfig { private final String schemasFolderPath; private final String descriptionsFolderPath; private final boolean separatedDefinitions; - private final boolean separatedOperations; + private final boolean separatedPaths; private final GroupBy pathsGroupedBy; private final OrderBy definitionsOrderedBy; private final Language outputLanguage; @@ -45,14 +45,14 @@ public class Swagger2MarkupConfig { * @param schemasFolderPath the path to the folder where the schema documents reside * @param descriptionsFolderPath the path to the folder where the description documents reside * @param separatedDefinitions specified if in addition to the definitions file, also separate definition files for each model definition should be created - * @param separatedOperations specified if in addition to the operations file, also separate path files for each operation should be created + * @param separatedPaths specified if in addition to the paths file, also separate path files for each path should be created * @param pathsGroupedBy specifies if the paths should be grouped by tags or stay as-is * @param definitionsOrderedBy specifies if the definitions should be ordered by natural ordering or stay as-is * @param outputLanguage specifies language of labels in output files * @param inlineSchemaDepthLevel specifies the max depth for inline object schema display (0 = no inline schemas) */ public Swagger2MarkupConfig(Swagger swagger, MarkupLanguage markupLanguage, String examplesFolderPath, - String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions, boolean separatedOperations, + String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions, boolean separatedPaths, GroupBy pathsGroupedBy, OrderBy definitionsOrderedBy, Language outputLanguage, int inlineSchemaDepthLevel) { this.swagger = swagger; @@ -61,7 +61,7 @@ public class Swagger2MarkupConfig { this.schemasFolderPath = schemasFolderPath; this.descriptionsFolderPath = descriptionsFolderPath; this.separatedDefinitions = separatedDefinitions; - this.separatedOperations = separatedOperations; + this.separatedPaths = separatedPaths; this.pathsGroupedBy = pathsGroupedBy; this.definitionsOrderedBy = definitionsOrderedBy; this.outputLanguage = outputLanguage; @@ -92,8 +92,8 @@ public class Swagger2MarkupConfig { return separatedDefinitions; } - public boolean isSeparatedOperations() { - return separatedOperations; + public boolean isSeparatedPaths() { + return separatedPaths; } public GroupBy getPathsGroupedBy() { From a76b7c545a676eb0100f2d38065b47de5a77cca6 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Fri, 5 Feb 2016 00:15:17 +0100 Subject: [PATCH 3/3] Localized Response inline type prefix --- .../swagger2markup/builder/document/PathsDocument.java | 5 +++-- src/main/resources/lang/labels_en.properties | 1 + src/main/resources/lang/labels_ru.properties | 1 + 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java index 1804470f..9bdb814a 100644 --- a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java +++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java @@ -56,7 +56,7 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank; */ public class PathsDocument extends MarkupDocument { - private static final String RESPONSE_INLINE_PREFIX = "Response"; + private final String RESPONSE; private final String PATHS; private final String RESOURCES; private final String PARAMETERS; @@ -89,6 +89,7 @@ public class PathsDocument extends MarkupDocument { ResourceBundle labels = ResourceBundle.getBundle("lang/labels", swagger2MarkupConfig.getOutputLanguage().toLocale()); + RESPONSE = labels.getString("response"); PATHS = labels.getString("paths"); RESOURCES = labels.getString("resources"); PARAMETERS = labels.getString("parameters"); @@ -539,7 +540,7 @@ public class PathsDocument extends MarkupDocument { Property property = response.getSchema(); Type type = PropertyUtils.getType(property); if (this.inlineSchemaDepthLevel > 0 && type instanceof ObjectType) { - String localTypeName = RESPONSE_INLINE_PREFIX + " " + entry.getKey(); + String localTypeName = RESPONSE + " " + entry.getKey(); type.setName(localTypeName); type.setUniqueName(uniqueTypeName(localTypeName)); diff --git a/src/main/resources/lang/labels_en.properties b/src/main/resources/lang/labels_en.properties index d9a220ee..6cc116ff 100644 --- a/src/main/resources/lang/labels_en.properties +++ b/src/main/resources/lang/labels_en.properties @@ -30,6 +30,7 @@ paths=Paths resources=Resources parameters=Parameters responses=Responses +response=Response example_curl=Example CURL request example_request=Example HTTP request example_response=Example HTTP response diff --git a/src/main/resources/lang/labels_ru.properties b/src/main/resources/lang/labels_ru.properties index 7ed23db3..7a7e293f 100644 --- a/src/main/resources/lang/labels_ru.properties +++ b/src/main/resources/lang/labels_ru.properties @@ -28,6 +28,7 @@ schemes=\u0421\u0445\u0435\u043C\u044B\:\u0020 paths=\u041F\u0443\u0442\u0438 resources=\u041E\u0442\u0432\u0435\u0442\u044B +response=Response parameters=\u041F\u0430\u0440\u0430\u043C\u0435\u0442\u0440\u044B responses=\u041E\u0442\u0432\u0435\u0442\u044B example_curl=\u041F\u0440\u0438\u043C\u0435\u0440 CURL \u0437\u0430\u043F\u0440\u043E\u0441\u0430