diff --git a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java index c340938e..f53fd2c1 100644 --- a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java +++ b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java @@ -17,9 +17,12 @@ * */ package io.github.robwin.swagger2markup; + 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.config.Swagger2MarkupConfig; -import io.github.robwin.swagger2markup.builder.document.*; import io.github.robwin.swagger2markup.utils.Consumer; import io.swagger.models.Swagger; import io.swagger.parser.SwaggerParser; @@ -142,6 +145,7 @@ public class Swagger2MarkupConverter { private OrderBy definitionsOrderedBy = OrderBy.NATURAL; private MarkupLanguage markupLanguage = MarkupLanguage.ASCIIDOC; private Language outputLanguage = Language.EN; + private Integer inlineSchemaDepthLevel = 0; /** * Creates a Builder using a given Swagger source. @@ -167,7 +171,7 @@ public class Swagger2MarkupConverter { public Swagger2MarkupConverter build(){ return new Swagger2MarkupConverter(new Swagger2MarkupConfig(swagger, markupLanguage, examplesFolderPath, schemasFolderPath, descriptionsFolderPath, separatedDefinitions, pathsGroupedBy, definitionsOrderedBy, - outputLanguage)); + outputLanguage, inlineSchemaDepthLevel)); } /** @@ -266,6 +270,17 @@ public class Swagger2MarkupConverter { this.outputLanguage = language; return this; } + + /** + * Specifies maximum depth level for inline object schema displaying (0 = no inline schemas) + * + * @param inlineSchemaDepthLevel + * @return the Swagger2MarkupConverter.Builder + */ + public Builder withInlineSchemaDepthLevel(Integer inlineSchemaDepthLevel) { + this.inlineSchemaDepthLevel = inlineSchemaDepthLevel; + 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 3be70a55..13fc8dcc 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 @@ -25,11 +25,13 @@ import io.github.robwin.swagger2markup.OrderBy; import io.github.robwin.swagger2markup.config.Swagger2MarkupConfig; import io.github.robwin.swagger2markup.type.ObjectType; import io.github.robwin.swagger2markup.type.Type; +import io.github.robwin.swagger2markup.utils.MarkupDocBuilderUtils; import io.swagger.models.ComposedModel; import io.swagger.models.Model; import io.swagger.models.RefModel; import io.swagger.models.properties.Property; import io.swagger.models.refs.RefFormat; +import org.apache.commons.collections.CollectionUtils; import org.apache.commons.collections.MapUtils; import org.apache.commons.io.FileUtils; import org.apache.commons.lang3.Validate; @@ -64,6 +66,7 @@ public class DefinitionsDocument extends MarkupDocument { private boolean separatedDefinitionsEnabled; private String outputDirectory; private final OrderBy definitionsOrderedBy; + private final Integer inlineSchemaDepthLevel; public DefinitionsDocument(Swagger2MarkupConfig swagger2MarkupConfig, String outputDirectory){ super(swagger2MarkupConfig); @@ -74,6 +77,7 @@ public class DefinitionsDocument extends MarkupDocument { JSON_SCHEMA = labels.getString("json_schema"); XML_SCHEMA = labels.getString("xml_schema"); + this.inlineSchemaDepthLevel = swagger2MarkupConfig.getInlineSchemaDepthLevel(); this.definitionsOrderedBy = swagger2MarkupConfig.getDefinitionsOrderedBy(); if(isNotBlank(swagger2MarkupConfig.getSchemasFolderPath())){ this.schemasEnabled = true; @@ -221,7 +225,9 @@ public class DefinitionsDocument extends MarkupDocument { private void propertiesSection(Map definitions, String definitionName, Model model, MarkupDocBuilder docBuilder){ Map properties = getAllProperties(definitions, model); Type type = new ObjectType(definitionName, properties); - typeProperties(type, new DefinitionPropertyDescriptor(type), docBuilder); + + List localDefinitions = typeProperties(type, inlineSchemaDepthLevel, new PropertyDescriptor(type), docBuilder); + inlineDefinitions(localDefinitions, inlineSchemaDepthLevel - 1, docBuilder); } private Map getAllProperties(Map definitions, Model model) { @@ -341,4 +347,16 @@ public class DefinitionsDocument extends MarkupDocument { } } } + + private void inlineDefinitions(List definitions, int depth, MarkupDocBuilder docBuilder) { + if(CollectionUtils.isNotEmpty(definitions)){ + for (Type definition: definitions) { + MarkupDocBuilderUtils.sectionTitleLevel(5, definition.getName(), definition.getUniqueName(), this.markupLanguage, docBuilder); + List localDefinitions = typeProperties(definition, depth, new DefinitionPropertyDescriptor(definition), docBuilder); + for (Type localDefinition : localDefinitions) + inlineDefinitions(Arrays.asList(localDefinition), depth - 1, docBuilder); + } + } + + } } diff --git a/src/main/java/io/github/robwin/swagger2markup/builder/document/MarkupDocument.java b/src/main/java/io/github/robwin/swagger2markup/builder/document/MarkupDocument.java index c83623e4..fffe7b73 100644 --- a/src/main/java/io/github/robwin/swagger2markup/builder/document/MarkupDocument.java +++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/MarkupDocument.java @@ -23,7 +23,9 @@ import io.github.robwin.markup.builder.MarkupDocBuilders; import io.github.robwin.markup.builder.MarkupLanguage; import io.github.robwin.swagger2markup.config.Swagger2MarkupConfig; import io.github.robwin.swagger2markup.type.ObjectType; +import io.github.robwin.swagger2markup.type.RefType; import io.github.robwin.swagger2markup.type.Type; +import io.github.robwin.swagger2markup.utils.MarkupDocBuilderUtils; import io.github.robwin.swagger2markup.utils.PropertyUtils; import io.swagger.models.Swagger; import io.swagger.models.properties.Property; @@ -117,7 +119,8 @@ public abstract class MarkupDocument { return type.displaySchema(markupLanguage); } - public void typeProperties(Type type, PropertyDescriptor propertyDescriptor, MarkupDocBuilder docBuilder) { + public List typeProperties(Type type, int depth, PropertyDescriptor propertyDescriptor, MarkupDocBuilder docBuilder) { + List localDefinitions = new ArrayList<>(); if (type instanceof ObjectType) { ObjectType objectType = (ObjectType) type; List headerAndContent = new ArrayList<>(); @@ -128,6 +131,15 @@ public abstract class MarkupDocument { Property property = propertyEntry.getValue(); String propertyName = propertyEntry.getKey(); Type propertyType = PropertyUtils.getType(property); + if (depth > 0 && propertyType instanceof ObjectType) { + String localTypeName = propertyName; + propertyType.setName(localTypeName); + propertyType.setUniqueName(uniqueTypeName(localTypeName)); + localDefinitions.add(propertyType); + + propertyType = new RefType(propertyType); + } + List content = Arrays.asList( propertyName, propertyDescriptor.getDescription(property, propertyName), @@ -139,6 +151,8 @@ public abstract class MarkupDocument { docBuilder.tableWithHeaderRow(headerAndContent); } } + + return localDefinitions; } public class 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 8d747384..c2b2f90e 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 @@ -66,7 +66,6 @@ public class PathsDocument extends MarkupDocument { private static final String DESCRIPTION_FOLDER_NAME = "paths"; private static final String DESCRIPTION_FILE_NAME = "description"; private final String PARAMETER; - private final String DEFINITIONS; private boolean examplesEnabled; @@ -74,6 +73,7 @@ public class PathsDocument extends MarkupDocument { private boolean handWrittenDescriptionsEnabled; private String descriptionsFolderPath; private final GroupBy pathsGroupedBy; + private final Integer inlineSchemaDepthLevel; public PathsDocument(Swagger2MarkupConfig swagger2MarkupConfig){ super(swagger2MarkupConfig); @@ -90,8 +90,8 @@ public class PathsDocument extends MarkupDocument { TYPE_COLUMN = labels.getString("type_column"); HTTP_CODE_COLUMN = labels.getString("http_code_column"); PARAMETER = labels.getString("parameter"); - DEFINITIONS = labels.getString("definitions"); + this.inlineSchemaDepthLevel = swagger2MarkupConfig.getInlineSchemaDepthLevel(); this.pathsGroupedBy = swagger2MarkupConfig.getPathsGroupedBy(); if(isNotBlank(swagger2MarkupConfig.getExamplesFolderPath())){ this.examplesEnabled = true; @@ -183,17 +183,14 @@ public class PathsDocument extends MarkupDocument { */ private void path(String methodAndPath, Operation operation) { if(operation != null){ - List localDefinitions = new ArrayList<>(); - pathTitle(methodAndPath, operation); descriptionSection(operation); - localDefinitions.addAll(parametersSection(operation)); - localDefinitions.addAll(responsesSection(operation)); + inlineDefinitions(parametersSection(operation), inlineSchemaDepthLevel); + inlineDefinitions(responsesSection(operation), inlineSchemaDepthLevel); consumesSection(operation); producesSection(operation); tagsSection(operation); examplesSection(operation); - localDefinitionsSection(localDefinitions); } } @@ -292,12 +289,12 @@ public class PathsDocument extends MarkupDocument { headerAndContent.add(join(header, DELIMITER)); for(Parameter parameter : parameters){ Type type = ParameterUtils.getType(parameter); - if (type instanceof ObjectType) { + if (inlineSchemaDepthLevel > 0 && type instanceof ObjectType) { String localTypeName = parameter.getName(); + type.setName(localTypeName); type.setUniqueName(uniqueTypeName(localTypeName)); localDefinitions.add(type); - type = new RefType(type); } String parameterType = WordUtils.capitalize(parameter.getIn() + PARAMETER); @@ -494,12 +491,12 @@ public class PathsDocument extends MarkupDocument { if(response.getSchema() != null){ Property property = response.getSchema(); Type type = PropertyUtils.getType(property); - if (type instanceof ObjectType) { + if (this.inlineSchemaDepthLevel > 0 && type instanceof ObjectType) { String localTypeName = "Response " + entry.getKey(); + type.setName(localTypeName); type.setUniqueName(uniqueTypeName(localTypeName)); localDefinitions.add(type); - type = new RefType(type); } csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + typeSchema(type)); @@ -513,17 +510,17 @@ public class PathsDocument extends MarkupDocument { return localDefinitions; } - private void localDefinitionsSection(List definitions) { + private void inlineDefinitions(List definitions, int depth) { if(CollectionUtils.isNotEmpty(definitions)){ - addPathSectionTitle(DEFINITIONS); - for (Type definition: definitions) { if(pathsGroupedBy.equals(GroupBy.AS_IS)){ MarkupDocBuilderUtils.sectionTitleLevel(4, definition.getName(), definition.getUniqueName(), this.markupLanguage, this.markupDocBuilder); }else{ MarkupDocBuilderUtils.sectionTitleLevel(5, definition.getName(), definition.getUniqueName(), this.markupLanguage, this.markupDocBuilder); } - typeProperties(definition, new PropertyDescriptor(definition), this.markupDocBuilder); + List localDefinitions = typeProperties(definition, depth, new PropertyDescriptor(definition), this.markupDocBuilder); + for (Type localDefinition : localDefinitions) + inlineDefinitions(Arrays.asList(localDefinition), depth - 1); } } 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 2f5d2111..14aee779 100644 --- a/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java +++ b/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java @@ -35,6 +35,7 @@ public class Swagger2MarkupConfig { private final GroupBy pathsGroupedBy; private final OrderBy definitionsOrderedBy; private final Language outputLanguage; + private final Integer inlineSchemaDepthLevel; /** * @param swagger the Swagger source @@ -46,10 +47,12 @@ public class Swagger2MarkupConfig { * @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, - GroupBy pathsGroupedBy, OrderBy definitionsOrderedBy, Language outputLanguage) { + GroupBy pathsGroupedBy, OrderBy definitionsOrderedBy, Language outputLanguage, + Integer inlineSchemaDepthLevel) { this.swagger = swagger; this.markupLanguage = markupLanguage; this.examplesFolderPath = examplesFolderPath; @@ -59,6 +62,7 @@ public class Swagger2MarkupConfig { this.pathsGroupedBy = pathsGroupedBy; this.definitionsOrderedBy = definitionsOrderedBy; this.outputLanguage = outputLanguage; + this.inlineSchemaDepthLevel = inlineSchemaDepthLevel; } public Swagger getSwagger() { @@ -96,4 +100,8 @@ public class Swagger2MarkupConfig { public Language getOutputLanguage() { return outputLanguage; } + + public Integer getInlineSchemaDepthLevel() { + return inlineSchemaDepthLevel; + } } diff --git a/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java b/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java index 4267bd3f..6d38a00b 100644 --- a/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java +++ b/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java @@ -65,6 +65,11 @@ public class MarkupDocBuilderUtils { MarkupDocBuilderUtils.anchor(title, language, docBuilder); docBuilder.boldTextLine(title); break; + case 6: + if (anchor == null) + MarkupDocBuilderUtils.anchor(title, language, docBuilder); + docBuilder.textLine(title); + break; default: throw new RuntimeException("Illegal section level : " + level); }