From aa34532b336d369ed205d8d7c408c940ad0f8793 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Mon, 1 Feb 2016 10:58:31 +0100 Subject: [PATCH 1/6] Factorized paths sections titles --- .../builder/document/PathsDocument.java | 63 +++++++------------ 1 file changed, 22 insertions(+), 41 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 72ee377b..6a9f5fda 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 @@ -225,6 +225,19 @@ public class PathsDocument extends MarkupDocument { } } + /** + * Adds a path section title to the document. + * + * @param title the path title + */ + private void addPathSectionTitle(String title) { + if(pathsGroupedBy.equals(GroupBy.AS_IS)){ + this.markupDocBuilder.sectionTitleLevel3(title); + }else{ + this.markupDocBuilder.sectionTitleLevel4(title); + } + } + /** * Adds a path description to the document. * @@ -257,11 +270,7 @@ public class PathsDocument extends MarkupDocument { private void pathDescription(String description) { if (isNotBlank(description)) { - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(DESCRIPTION); - }else{ - this.markupDocBuilder.sectionTitleLevel4(DESCRIPTION); - } + addPathSectionTitle(DESCRIPTION); this.markupDocBuilder.paragraph(description); } } @@ -285,11 +294,7 @@ public class PathsDocument extends MarkupDocument { ParameterUtils.getDefaultValue(parameter)); headerAndContent.add(join(content, DELIMITER)); } - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(PARAMETERS); - }else{ - this.markupDocBuilder.sectionTitleLevel4(PARAMETERS); - } + addPathSectionTitle(PARAMETERS); this.markupDocBuilder.tableWithHeaderRow(headerAndContent); } } @@ -333,11 +338,7 @@ public class PathsDocument extends MarkupDocument { private void consumesSection(Operation operation) { List consumes = operation.getConsumes(); if(CollectionUtils.isNotEmpty(consumes)){ - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(CONSUMES); - }else{ - this.markupDocBuilder.sectionTitleLevel4(CONSUMES); - } + addPathSectionTitle(CONSUMES); this.markupDocBuilder.unorderedList(consumes); } @@ -346,11 +347,7 @@ public class PathsDocument extends MarkupDocument { private void producesSection(Operation operation) { List produces = operation.getProduces(); if(CollectionUtils.isNotEmpty(produces)){ - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(PRODUCES); - }else{ - this.markupDocBuilder.sectionTitleLevel4(PRODUCES); - } + addPathSectionTitle(PRODUCES); this.markupDocBuilder.unorderedList(produces); } } @@ -359,7 +356,7 @@ public class PathsDocument extends MarkupDocument { if(pathsGroupedBy.equals(GroupBy.AS_IS)) { List tags = operation.getTags(); if (CollectionUtils.isNotEmpty(tags)) { - this.markupDocBuilder.sectionTitleLevel3(TAGS); + addPathSectionTitle(TAGS); this.markupDocBuilder.unorderedList(tags); } } @@ -379,30 +376,18 @@ public class PathsDocument extends MarkupDocument { String exampleFolder = summary.replace(".", "").replace(" ", "_").toLowerCase(); Optional curlExample = example(exampleFolder, CURL_EXAMPLE_FILE_NAME); if(curlExample.isPresent()){ - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(EXAMPLE_CURL); - }else{ - this.markupDocBuilder.sectionTitleLevel4(EXAMPLE_CURL); - } + addPathSectionTitle(EXAMPLE_CURL); this.markupDocBuilder.paragraph(curlExample.get()); } Optional requestExample = example(exampleFolder, REQUEST_EXAMPLE_FILE_NAME); if(requestExample.isPresent()){ - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(EXAMPLE_REQUEST); - }else{ - this.markupDocBuilder.sectionTitleLevel4(EXAMPLE_REQUEST); - } + addPathSectionTitle(EXAMPLE_REQUEST); this.markupDocBuilder.paragraph(requestExample.get()); } Optional responseExample = example(exampleFolder, RESPONSE_EXAMPLE_FILE_NAME); if(responseExample.isPresent()){ - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(EXAMPLE_RESPONSE); - }else{ - this.markupDocBuilder.sectionTitleLevel4(EXAMPLE_RESPONSE); - } + addPathSectionTitle(EXAMPLE_RESPONSE); this.markupDocBuilder.paragraph(responseExample.get()); } }else{ @@ -494,11 +479,7 @@ public class PathsDocument extends MarkupDocument { csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + "No Content"); } } - if(pathsGroupedBy.equals(GroupBy.AS_IS)){ - this.markupDocBuilder.sectionTitleLevel3(RESPONSES); - }else{ - this.markupDocBuilder.sectionTitleLevel4(RESPONSES); - } + addPathSectionTitle(RESPONSES); this.markupDocBuilder.tableWithHeaderRow(csvContent); } } From 4f15ea9ed751563721f66886ba7f4db95960d1f8 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Mon, 1 Feb 2016 10:59:38 +0100 Subject: [PATCH 2/6] Corrected warnings --- .../robwin/swagger2markup/builder/document/PathsDocument.java | 4 ++-- 1 file changed, 2 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 6a9f5fda..0c5ff1de 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 @@ -413,7 +413,7 @@ public class PathsDocument extends MarkupDocument { logger.info("Example file processed: {}", path); } try { - return Optional.fromNullable(FileUtils.readFileToString(path.toFile(), StandardCharsets.UTF_8).trim()); + return Optional.of(FileUtils.readFileToString(path.toFile(), StandardCharsets.UTF_8).trim()); } catch (IOException e) { if (logger.isWarnEnabled()) { logger.warn(String.format("Failed to read example file: %s", path), e); @@ -446,7 +446,7 @@ public class PathsDocument extends MarkupDocument { logger.info("Description file processed: {}", path); } try { - return Optional.fromNullable(FileUtils.readFileToString(path.toFile(), StandardCharsets.UTF_8).trim()); + return Optional.of(FileUtils.readFileToString(path.toFile(), StandardCharsets.UTF_8).trim()); } catch (IOException e) { if (logger.isWarnEnabled()) { logger.warn(String.format("Failed to read description file: %s", path), e); From a6654b65a9dda6af1d2888a0683960165e04bf34 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Mon, 1 Feb 2016 16:10:30 +0100 Subject: [PATCH 3/6] Genericized the type system between models, parameters, properties, etc ... for further refactoring *Utils display logic is removed from *Utils which are now just adapters from Swagger model to *Type. *Type now have the display logic. --- .../builder/document/DefinitionsDocument.java | 11 +++- .../builder/document/PathsDocument.java | 17 +++++-- .../robwin/swagger2markup/type/ArrayType.java | 27 ++++++++++ .../robwin/swagger2markup/type/BasicType.java | 27 ++++++++++ .../robwin/swagger2markup/type/EnumType.java | 22 ++++++++ .../swagger2markup/type/ObjectType.java | 30 +++++++++++ .../robwin/swagger2markup/type/RefType.java | 20 ++++++++ .../robwin/swagger2markup/type/Type.java | 24 +++++++++ .../swagger2markup/utils/ModelUtils.java | 23 ++++----- .../swagger2markup/utils/ParameterUtils.java | 51 ++++++------------- .../swagger2markup/utils/PropertyUtils.java | 23 ++++----- 11 files changed, 209 insertions(+), 66 deletions(-) create mode 100644 src/main/java/io/github/robwin/swagger2markup/type/ArrayType.java create mode 100644 src/main/java/io/github/robwin/swagger2markup/type/BasicType.java create mode 100644 src/main/java/io/github/robwin/swagger2markup/type/EnumType.java create mode 100644 src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java create mode 100644 src/main/java/io/github/robwin/swagger2markup/type/RefType.java create mode 100644 src/main/java/io/github/robwin/swagger2markup/type/Type.java 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 0d47d623..0a64195a 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 @@ -23,6 +23,7 @@ import io.github.robwin.markup.builder.MarkupDocBuilder; import io.github.robwin.markup.builder.MarkupDocBuilders; import io.github.robwin.swagger2markup.OrderBy; import io.github.robwin.swagger2markup.config.Swagger2MarkupConfig; +import io.github.robwin.swagger2markup.type.Type; import io.github.robwin.swagger2markup.utils.PropertyUtils; import io.swagger.models.ComposedModel; import io.swagger.models.Model; @@ -191,6 +192,13 @@ public class DefinitionsDocument extends MarkupDocument { propertiesSection(definitions, definitionName, model, docBuilder); } + private String displayType(Type type) { + if (type == null) + return "Unknown"; + else + return type.displaySchema(markupLanguage); + } + private void propertiesSection(Map definitions, String definitionName, Model model, MarkupDocBuilder docBuilder){ Map properties = getAllProperties(definitions, model); List headerAndContent = new ArrayList<>(); @@ -200,11 +208,12 @@ public class DefinitionsDocument extends MarkupDocument { for (Map.Entry propertyEntry : properties.entrySet()) { Property property = propertyEntry.getValue(); String propertyName = propertyEntry.getKey(); + Type type = PropertyUtils.getType(property); List content = Arrays.asList( propertyName, propertyDescription(definitionName, propertyName, property), Boolean.toString(property.getRequired()), - PropertyUtils.getType(property, markupLanguage), + displayType(type), PropertyUtils.getDefaultValue(property)); headerAndContent.add(join(content, DELIMITER)); } 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 0c5ff1de..fc7453dc 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 @@ -22,6 +22,7 @@ import com.google.common.base.Optional; import com.google.common.collect.Multimap; import io.github.robwin.swagger2markup.GroupBy; import io.github.robwin.swagger2markup.config.Swagger2MarkupConfig; +import io.github.robwin.swagger2markup.type.Type; import io.github.robwin.swagger2markup.utils.ParameterUtils; import io.github.robwin.swagger2markup.utils.PropertyUtils; import io.swagger.models.*; @@ -128,6 +129,13 @@ public class PathsDocument extends MarkupDocument { return this; } + private String displayType(Type type) { + if (type == null) + return "Unknown"; + else + return type.displaySchema(markupLanguage); + } + /** * Builds all paths of the Swagger model. Either grouped as-is or by tags. */ @@ -283,14 +291,15 @@ public class PathsDocument extends MarkupDocument { List header = Arrays.asList(TYPE_COLUMN, NAME_COLUMN, DESCRIPTION_COLUMN, REQUIRED_COLUMN, SCHEMA_COLUMN, DEFAULT_COLUMN); headerAndContent.add(join(header, DELIMITER)); for(Parameter parameter : parameters){ - String type = ParameterUtils.getType(parameter, markupLanguage); + Type type = ParameterUtils.getType(parameter); String parameterType = WordUtils.capitalize(parameter.getIn() + PARAMETER); // Table content row List content = Arrays.asList( parameterType, parameter.getName(), parameterDescription(operation, parameter), - Boolean.toString(parameter.getRequired()), type, + Boolean.toString(parameter.getRequired()), + displayType(type), ParameterUtils.getDefaultValue(parameter)); headerAndContent.add(join(content, DELIMITER)); } @@ -473,8 +482,8 @@ public class PathsDocument extends MarkupDocument { Response response = entry.getValue(); if(response.getSchema() != null){ Property property = response.getSchema(); - String type = PropertyUtils.getType(property, markupLanguage); - csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + type); + Type type = PropertyUtils.getType(property); + csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + displayType(type)); }else{ csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + "No Content"); } diff --git a/src/main/java/io/github/robwin/swagger2markup/type/ArrayType.java b/src/main/java/io/github/robwin/swagger2markup/type/ArrayType.java new file mode 100644 index 00000000..797ca5a2 --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/type/ArrayType.java @@ -0,0 +1,27 @@ +package io.github.robwin.swagger2markup.type; + +import io.github.robwin.markup.builder.MarkupLanguage; + +public class ArrayType extends Type { + + protected String collectionFormat; + protected Type ofType; + + public ArrayType(String name, Type ofType) { + this(name, ofType, null); + } + + public ArrayType(String name, Type ofType, String collectionFormat) { + super(name == null ? "array" : name); + this.collectionFormat = collectionFormat; + this.ofType = ofType; + } + + @Override + public String displaySchema(MarkupLanguage language) { + String collectionFormat = ""; + if (this.collectionFormat != null) + collectionFormat = this.collectionFormat + " "; + return collectionFormat + ofType.displaySchema(language) + " array"; + } +} diff --git a/src/main/java/io/github/robwin/swagger2markup/type/BasicType.java b/src/main/java/io/github/robwin/swagger2markup/type/BasicType.java new file mode 100644 index 00000000..3af7459c --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/type/BasicType.java @@ -0,0 +1,27 @@ +package io.github.robwin.swagger2markup.type; + +import io.github.robwin.markup.builder.MarkupLanguage; + +import static org.apache.commons.lang3.StringUtils.isNotBlank; + +public class BasicType extends Type { + + protected String format; + + public BasicType(String name) { + this(name, null); + } + + public BasicType(String name, String format) { + super(name); + this.format = format; + } + + @Override + public String displaySchema(MarkupLanguage language) { + if (isNotBlank(this.format)) + return this.name + "(" + this.format + ")"; + else + return this.name; + } +} diff --git a/src/main/java/io/github/robwin/swagger2markup/type/EnumType.java b/src/main/java/io/github/robwin/swagger2markup/type/EnumType.java new file mode 100644 index 00000000..9ed9ff29 --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/type/EnumType.java @@ -0,0 +1,22 @@ +package io.github.robwin.swagger2markup.type; + +import io.github.robwin.markup.builder.MarkupLanguage; + +import java.util.List; + +import static org.apache.commons.lang3.StringUtils.join; + +public class EnumType extends Type { + + protected List values; + + public EnumType(String name, List values) { + super(name == null ? "enum" : name); + this.values = values; + } + + @Override + public String displaySchema(MarkupLanguage language) { + return "enum" + " (" + join(values, ", ") + ")"; + } +} diff --git a/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java b/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java new file mode 100644 index 00000000..4ae76482 --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java @@ -0,0 +1,30 @@ +package io.github.robwin.swagger2markup.type; + +import io.github.robwin.markup.builder.MarkupLanguage; +import io.swagger.models.properties.Property; + +import java.util.List; +import java.util.Map; + +public class ObjectType extends Type { + + protected Map properties; + + public ObjectType(String name, Map properties) { + super(name == null ? "object" : name); + this.properties = properties; + } + + @Override + public String displaySchema(MarkupLanguage language) { + return "object"; + } + + public Map getProperties() { + return properties; + } + + public void setProperties(Map properties) { + this.properties = properties; + } +} diff --git a/src/main/java/io/github/robwin/swagger2markup/type/RefType.java b/src/main/java/io/github/robwin/swagger2markup/type/RefType.java new file mode 100644 index 00000000..665a1695 --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/type/RefType.java @@ -0,0 +1,20 @@ +package io.github.robwin.swagger2markup.type; + +import io.github.robwin.markup.builder.MarkupLanguage; + +public class RefType extends Type { + + public RefType(String name) { + super(name); + } + + @Override + public String displaySchema(MarkupLanguage language) { + switch (language) { + case ASCIIDOC: + return "<<" + getName() + ">>"; + default: + return getName(); + } + } +} diff --git a/src/main/java/io/github/robwin/swagger2markup/type/Type.java b/src/main/java/io/github/robwin/swagger2markup/type/Type.java new file mode 100644 index 00000000..53c5a94c --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/type/Type.java @@ -0,0 +1,24 @@ +package io.github.robwin.swagger2markup.type; + +import io.github.robwin.markup.builder.MarkupLanguage; +import org.apache.commons.lang3.Validate; + +public abstract class Type { + + protected String name; + + public Type() { + } + + public Type(String name) { + Validate.notBlank(name); + + this.name = name; + } + + public String getName() { + return name; + } + + public abstract String displaySchema(MarkupLanguage language); +} diff --git a/src/main/java/io/github/robwin/swagger2markup/utils/ModelUtils.java b/src/main/java/io/github/robwin/swagger2markup/utils/ModelUtils.java index fd16a310..9e2d5fac 100644 --- a/src/main/java/io/github/robwin/swagger2markup/utils/ModelUtils.java +++ b/src/main/java/io/github/robwin/swagger2markup/utils/ModelUtils.java @@ -18,35 +18,34 @@ */ package io.github.robwin.swagger2markup.utils; +import io.github.robwin.swagger2markup.type.ArrayType; +import io.github.robwin.swagger2markup.type.ObjectType; +import io.github.robwin.swagger2markup.type.RefType; +import io.github.robwin.swagger2markup.type.Type; import io.swagger.models.ArrayModel; import io.swagger.models.Model; import io.swagger.models.ModelImpl; import io.swagger.models.RefModel; -import io.github.robwin.markup.builder.MarkupLanguage; import org.apache.commons.lang3.Validate; public final class ModelUtils { /** - * Retrieves the type of a model, or otherwise "NOT FOUND" + * Retrieves the type of a model, or otherwise null * * @param model the model - * @param markupLanguage the markup language which is used to generate the files - * @return the type of the model, or otherwise "NOT FOUND" + * @return the type of the model, or otherwise null */ - public static String getType(Model model, MarkupLanguage markupLanguage) { + public static Type getType(Model model) { Validate.notNull(model, "model must not be null!"); if (model instanceof ModelImpl) { - return ((ModelImpl) model).getType(); + return new ObjectType(null, model.getProperties()); } else if (model instanceof RefModel) { - switch (markupLanguage){ - case ASCIIDOC: return "<<" + ((RefModel) model).getSimpleRef() + ">>"; - default: return ((RefModel) model).getSimpleRef(); - } + return new RefType(((RefModel) model).getSimpleRef()); } else if (model instanceof ArrayModel) { ArrayModel arrayModel = ((ArrayModel) model); - return PropertyUtils.getType(arrayModel.getItems(), markupLanguage) + " " + arrayModel.getType(); + return new ArrayType(null, PropertyUtils.getType(arrayModel.getItems())); } - return "NOT FOUND"; + return null; } } diff --git a/src/main/java/io/github/robwin/swagger2markup/utils/ParameterUtils.java b/src/main/java/io/github/robwin/swagger2markup/utils/ParameterUtils.java index e8c0789d..112c0a77 100644 --- a/src/main/java/io/github/robwin/swagger2markup/utils/ParameterUtils.java +++ b/src/main/java/io/github/robwin/swagger2markup/utils/ParameterUtils.java @@ -18,7 +18,7 @@ */ package io.github.robwin.swagger2markup.utils; -import io.github.robwin.markup.builder.MarkupLanguage; +import io.github.robwin.swagger2markup.type.*; import io.swagger.models.Model; import io.swagger.models.parameters.AbstractSerializableParameter; import io.swagger.models.parameters.BodyParameter; @@ -29,28 +29,27 @@ import org.apache.commons.lang3.Validate; import java.util.List; -import static org.apache.commons.lang3.StringUtils.*; +import static org.apache.commons.lang3.StringUtils.defaultString; public final class ParameterUtils { /** - * Retrieves the type of a parameter, or otherwise an empty String + * Retrieves the type of a parameter, or otherwise null * * @param parameter the parameter - * @param markupLanguage the markup language which is used to generate the files - * @return the type of the parameter, or otherwise an empty String + * @return the type of the parameter, or otherwise null */ - public static String getType(Parameter parameter, MarkupLanguage markupLanguage){ - Validate.notNull(parameter, "property must not be null!"); - String type = "NOT FOUND"; + public static Type getType(Parameter parameter){ + Validate.notNull(parameter, "parameter must not be null!"); + Type type = null; if(parameter instanceof BodyParameter){ BodyParameter bodyParameter = (BodyParameter)parameter; Model model = bodyParameter.getSchema(); if(model != null){ - type = ModelUtils.getType(model, markupLanguage); + type = ModelUtils.getType(model); }else{ - type = "string"; + type = new BasicType("string"); } } @@ -58,38 +57,18 @@ public final class ParameterUtils { AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter)parameter; List enums = serializableParameter.getEnum(); if(CollectionUtils.isNotEmpty(enums)){ - type = "enum" + " (" + join(enums, ", ") + ")"; + type = new EnumType(null, enums); }else{ - type = getTypeWithFormat(serializableParameter.getType(), serializableParameter.getFormat()); + type = new BasicType(serializableParameter.getType(), serializableParameter.getFormat()); } - if(type.equals("array")){ + if(type.getName().equals("array")){ String collectionFormat = serializableParameter.getCollectionFormat(); - type = collectionFormat + " " + PropertyUtils.getType(serializableParameter.getItems(), markupLanguage) + " " + type; + type = new ArrayType(null, PropertyUtils.getType(serializableParameter.getItems()), collectionFormat); } } else if(parameter instanceof RefParameter){ RefParameter refParameter = (RefParameter)parameter; - switch (markupLanguage){ - case ASCIIDOC: return "<<" + refParameter.getSimpleRef() + ">>"; - default: return refParameter.getSimpleRef(); - } - } - return defaultString(type); - } - - /** - * Adds the format to the type, if a format is available - * - * @param typeWithoutFormat the type - * @param format the format - * @return returns the type and format, if a format is available - */ - private static String getTypeWithFormat(String typeWithoutFormat, String format) { - String type; - if(isNotBlank(format)){ - type = defaultString(typeWithoutFormat) + " (" + format + ")"; - }else{ - type = defaultString(typeWithoutFormat); + type = new RefType(refParameter.getSimpleRef()); } return type; } @@ -101,7 +80,7 @@ public final class ParameterUtils { * @return the default value of the parameter, or otherwise an empty String */ public static String getDefaultValue(Parameter parameter){ - Validate.notNull(parameter, "property must not be null!"); + Validate.notNull(parameter, "parameter must not be null!"); String defaultValue = ""; if(parameter instanceof AbstractSerializableParameter){ AbstractSerializableParameter serializableParameter = (AbstractSerializableParameter)parameter; diff --git a/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java b/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java index e9b234b7..2f68fb54 100644 --- a/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java +++ b/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java @@ -19,6 +19,7 @@ package io.github.robwin.swagger2markup.utils; import io.github.robwin.markup.builder.MarkupLanguage; +import io.github.robwin.swagger2markup.type.*; import io.swagger.models.properties.*; import org.apache.commons.collections.CollectionUtils; import org.apache.commons.lang3.Validate; @@ -34,39 +35,35 @@ public final class PropertyUtils { * Retrieves the type and format of a property. * * @param property the property - * @param markupLanguage the markup language which is used to generate the files * @return the type of the property */ - public static String getType(Property property, MarkupLanguage markupLanguage){ + public static Type getType(Property property){ Validate.notNull(property, "property must not be null!"); - String type; + Type type = null; if(property instanceof RefProperty){ RefProperty refProperty = (RefProperty)property; - switch (markupLanguage){ - case ASCIIDOC: return "<<" + refProperty.getSimpleRef() + ">>"; - default: return refProperty.getSimpleRef(); - } + type = new RefType(refProperty.getSimpleRef()); }else if(property instanceof ArrayProperty){ ArrayProperty arrayProperty = (ArrayProperty)property; Property items = arrayProperty.getItems(); - type = getType(items, markupLanguage) + " " + arrayProperty.getType(); + type = new ArrayType(null, getType(items)); }else if(property instanceof StringProperty){ StringProperty stringProperty = (StringProperty)property; List enums = stringProperty.getEnum(); if(CollectionUtils.isNotEmpty(enums)){ - type = "enum" + " (" + join(enums, ", ") + ")"; + type = new EnumType(null, enums); }else{ - type = property.getType(); + type = new BasicType(property.getType()); } } else{ if(isNotBlank(property.getFormat())){ - type = defaultString(property.getType()) + " (" + property.getFormat() + ")"; + type = new BasicType(property.getType(), property.getFormat()); }else{ - type = property.getType(); + type = new BasicType(property.getType()); } } - return defaultString(type); + return type; } /** From 650431b8ce174d1b1cbb73547325c9e2f4b8476a Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Mon, 1 Feb 2016 16:15:56 +0100 Subject: [PATCH 4/6] Support for response inline objects --- .../io/github/robwin/swagger2markup/utils/PropertyUtils.java | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java b/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java index 2f68fb54..288c7ca6 100644 --- a/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java +++ b/src/main/java/io/github/robwin/swagger2markup/utils/PropertyUtils.java @@ -55,6 +55,8 @@ public final class PropertyUtils { }else{ type = new BasicType(property.getType()); } + }else if(property instanceof ObjectProperty) { + type = new ObjectType(null, ((ObjectProperty) property).getProperties()); } else{ if(isNotBlank(property.getFormat())){ From a16617880f505469a66079cfab73c5ffdd5c9946 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Mon, 1 Feb 2016 17:38:06 +0100 Subject: [PATCH 5/6] Factorized the display of type properties table --- .../builder/document/DefinitionsDocument.java | 68 +++++++------------ .../builder/document/MarkupDocument.java | 55 ++++++++++++++- .../builder/document/PathsDocument.java | 11 +-- 3 files changed, 82 insertions(+), 52 deletions(-) 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 0a64195a..e91aa4e4 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 @@ -23,8 +23,8 @@ import io.github.robwin.markup.builder.MarkupDocBuilder; import io.github.robwin.markup.builder.MarkupDocBuilders; 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.PropertyUtils; import io.swagger.models.ComposedModel; import io.swagger.models.Model; import io.swagger.models.RefModel; @@ -192,33 +192,35 @@ public class DefinitionsDocument extends MarkupDocument { propertiesSection(definitions, definitionName, model, docBuilder); } - private String displayType(Type type) { - if (type == null) - return "Unknown"; - else - return type.displaySchema(markupLanguage); + private class DefinitionPropertyDescriptor extends PropertyDescriptor { + + public DefinitionPropertyDescriptor(Type type) { + super(type); + } + + @Override + public String getDescription(Property property) { + String description; + if(handWrittenDescriptionsEnabled){ + description = handWrittenPathDescription(type.getName().toLowerCase() + "/" + property.getName().toLowerCase(), DESCRIPTION_FILE_NAME); + if(isBlank(description)) { + if (logger.isInfoEnabled()) { + logger.info("Hand-written description file cannot be read. Trying to use description from Swagger source."); + } + description = defaultString(property.getDescription()); + } + } + else{ + description = defaultString(property.getDescription()); + } + return description; + } } private void propertiesSection(Map definitions, String definitionName, Model model, MarkupDocBuilder docBuilder){ Map properties = getAllProperties(definitions, model); - List headerAndContent = new ArrayList<>(); - List header = Arrays.asList(NAME_COLUMN, DESCRIPTION_COLUMN, REQUIRED_COLUMN, SCHEMA_COLUMN, DEFAULT_COLUMN); - headerAndContent.add(join(header, DELIMITER)); - if(MapUtils.isNotEmpty(properties)){ - for (Map.Entry propertyEntry : properties.entrySet()) { - Property property = propertyEntry.getValue(); - String propertyName = propertyEntry.getKey(); - Type type = PropertyUtils.getType(property); - List content = Arrays.asList( - propertyName, - propertyDescription(definitionName, propertyName, property), - Boolean.toString(property.getRequired()), - displayType(type), - PropertyUtils.getDefaultValue(property)); - headerAndContent.add(join(content, DELIMITER)); - } - docBuilder.tableWithHeaderRow(headerAndContent); - } + Type type = new ObjectType(definitionName, properties); + typeProperties(type, docBuilder, new DefinitionPropertyDescriptor(type)); } private Map getAllProperties(Map definitions, Model model) { @@ -276,24 +278,6 @@ public class DefinitionsDocument extends MarkupDocument { } } - private String propertyDescription(String definitionName, String propertyName, Property property) { - String description; - if(handWrittenDescriptionsEnabled){ - description = handWrittenPathDescription(definitionName.toLowerCase() + "/" + propertyName.toLowerCase(), DESCRIPTION_FILE_NAME); - if(isBlank(description)) { - if (logger.isInfoEnabled()) { - logger.info("Hand-written description file cannot be read. Trying to use description from Swagger source."); - } - description = defaultString(property.getDescription()); - } - } - else{ - description = defaultString(property.getDescription()); - } - return description; - } - - /** * Reads a hand-written description * 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 de56bb19..0f1bc1e3 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 @@ -22,13 +22,21 @@ import io.github.robwin.markup.builder.MarkupDocBuilder; 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.Type; +import io.github.robwin.swagger2markup.utils.PropertyUtils; import io.swagger.models.Swagger; +import io.swagger.models.properties.Property; +import org.apache.commons.collections.MapUtils; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import java.io.IOException; import java.nio.charset.Charset; -import java.util.ResourceBundle; +import java.util.*; + +import static org.apache.commons.lang3.StringUtils.defaultString; +import static org.apache.commons.lang3.StringUtils.join; /** * @author Robert Winkler @@ -94,4 +102,49 @@ public abstract class MarkupDocument { public void writeToFile(String directory, String fileName, Charset charset) throws IOException{ markupDocBuilder.writeToFile(directory, fileName, charset); } + + public String typeSchema(Type type) { + if (type == null) + return "Unknown"; + else + return type.displaySchema(markupLanguage); + } + + public void typeProperties(Type type, MarkupDocBuilder docBuilder, PropertyDescriptor propertyDescriptor) { + if (type instanceof ObjectType) { + ObjectType objectType = (ObjectType)type; + List headerAndContent = new ArrayList<>(); + List header = Arrays.asList(NAME_COLUMN, DESCRIPTION_COLUMN, REQUIRED_COLUMN, SCHEMA_COLUMN, DEFAULT_COLUMN); + headerAndContent.add(join(header, DELIMITER)); + if (MapUtils.isNotEmpty(objectType.getProperties())) { + for (Map.Entry propertyEntry : objectType.getProperties().entrySet()) { + Property property = propertyEntry.getValue(); + String propertyName = propertyEntry.getKey(); + Type propertyType = PropertyUtils.getType(property); + List content = Arrays.asList( + propertyName, + propertyDescriptor.getDescription(property), + Boolean.toString(property.getRequired()), + typeSchema(propertyType), + PropertyUtils.getDefaultValue(property)); + headerAndContent.add(join(content, DELIMITER)); + } + docBuilder.tableWithHeaderRow(headerAndContent); + } + } + } + + public class PropertyDescriptor { + protected Type type; + + public PropertyDescriptor(Type type) { + this.type = type; + } + + public String getDescription(Property property) { + return defaultString(property.getDescription()); + } + } + + } 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 fc7453dc..447b5e13 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 @@ -129,13 +129,6 @@ public class PathsDocument extends MarkupDocument { return this; } - private String displayType(Type type) { - if (type == null) - return "Unknown"; - else - return type.displaySchema(markupLanguage); - } - /** * Builds all paths of the Swagger model. Either grouped as-is or by tags. */ @@ -299,7 +292,7 @@ public class PathsDocument extends MarkupDocument { parameter.getName(), parameterDescription(operation, parameter), Boolean.toString(parameter.getRequired()), - displayType(type), + typeSchema(type), ParameterUtils.getDefaultValue(parameter)); headerAndContent.add(join(content, DELIMITER)); } @@ -483,7 +476,7 @@ public class PathsDocument extends MarkupDocument { if(response.getSchema() != null){ Property property = response.getSchema(); Type type = PropertyUtils.getType(property); - csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + displayType(type)); + csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + typeSchema(type)); }else{ csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + "No Content"); } From 7d53a8aedbe51df35a970213a7782a7ac4016f04 Mon Sep 17 00:00:00 2001 From: Hugo de Paix de Coeur Date: Mon, 1 Feb 2016 20:14:40 +0100 Subject: [PATCH 6/6] Managed inline schemas in parameters and responses (depth level = 1) Inline schemas in definitions are still to be managed. --- .../builder/document/DefinitionsDocument.java | 6 +- .../builder/document/MarkupDocument.java | 58 +++++++++++++++---- .../builder/document/PathsDocument.java | 52 +++++++++++++++-- .../swagger2markup/type/ObjectType.java | 1 - .../robwin/swagger2markup/type/RefType.java | 12 ++-- .../robwin/swagger2markup/type/Type.java | 19 +++++- .../utils/MarkupDocBuilderUtils.java | 41 +++++++++++++ 7 files changed, 163 insertions(+), 26 deletions(-) create mode 100644 src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java 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 e91aa4e4..66222f20 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 @@ -199,10 +199,10 @@ public class DefinitionsDocument extends MarkupDocument { } @Override - public String getDescription(Property property) { + public String getDescription(Property property, String propertyName) { String description; if(handWrittenDescriptionsEnabled){ - description = handWrittenPathDescription(type.getName().toLowerCase() + "/" + property.getName().toLowerCase(), DESCRIPTION_FILE_NAME); + description = handWrittenPathDescription(type.getName().toLowerCase() + "/" + propertyName.toLowerCase(), DESCRIPTION_FILE_NAME); if(isBlank(description)) { if (logger.isInfoEnabled()) { logger.info("Hand-written description file cannot be read. Trying to use description from Swagger source."); @@ -220,7 +220,7 @@ 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, docBuilder, new DefinitionPropertyDescriptor(type)); + typeProperties(type, new DefinitionPropertyDescriptor(type), docBuilder); } private Map getAllProperties(Map definitions, Model model) { 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 0f1bc1e3..767d40ba 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 @@ -24,6 +24,7 @@ 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.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; @@ -34,6 +35,7 @@ import org.slf4j.LoggerFactory; import java.io.IOException; import java.nio.charset.Charset; import java.util.*; +import java.util.concurrent.atomic.AtomicInteger; import static org.apache.commons.lang3.StringUtils.defaultString; import static org.apache.commons.lang3.StringUtils.join; @@ -58,7 +60,9 @@ public abstract class MarkupDocument { protected MarkupLanguage markupLanguage; protected MarkupDocBuilder markupDocBuilder; - MarkupDocument(Swagger2MarkupConfig swagger2MarkupConfig){ + protected static AtomicInteger idCount = new AtomicInteger(0); + + MarkupDocument(Swagger2MarkupConfig swagger2MarkupConfig) { this.swagger = swagger2MarkupConfig.getSwagger(); this.markupLanguage = swagger2MarkupConfig.getMarkupLanguage(); this.markupDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage); @@ -76,18 +80,22 @@ public abstract class MarkupDocument { TAGS = labels.getString("tags"); } + public Integer getNextId() { + return idCount.getAndIncrement(); + } + /** * Builds the MarkupDocument. * * @return the built MarkupDocument * @throws IOException if the files to include are not readable */ - public abstract MarkupDocument build() throws IOException ; + public abstract MarkupDocument build() throws IOException; /** * Returns a string representation of the document. */ - public String toString(){ + public String toString() { return markupDocBuilder.toString(); } @@ -95,14 +103,18 @@ public abstract class MarkupDocument { * Writes the content of the builder to a file and clears the builder. * * @param directory the directory where the generated file should be stored - * @param fileName the name of the file - * @param charset the the charset to use for encoding + * @param fileName the name of the file + * @param charset the the charset to use for encoding * @throws IOException if the file cannot be written */ - public void writeToFile(String directory, String fileName, Charset charset) throws IOException{ + public void writeToFile(String directory, String fileName, Charset charset) throws IOException { markupDocBuilder.writeToFile(directory, fileName, charset); } + public String uniqueTypeName(String name) { + return name + "-" + getNextId(); + } + public String typeSchema(Type type) { if (type == null) return "Unknown"; @@ -110,9 +122,9 @@ public abstract class MarkupDocument { return type.displaySchema(markupLanguage); } - public void typeProperties(Type type, MarkupDocBuilder docBuilder, PropertyDescriptor propertyDescriptor) { + public void typeProperties(Type type, PropertyDescriptor propertyDescriptor, MarkupDocBuilder docBuilder) { if (type instanceof ObjectType) { - ObjectType objectType = (ObjectType)type; + ObjectType objectType = (ObjectType) type; List headerAndContent = new ArrayList<>(); List header = Arrays.asList(NAME_COLUMN, DESCRIPTION_COLUMN, REQUIRED_COLUMN, SCHEMA_COLUMN, DEFAULT_COLUMN); headerAndContent.add(join(header, DELIMITER)); @@ -123,7 +135,7 @@ public abstract class MarkupDocument { Type propertyType = PropertyUtils.getType(property); List content = Arrays.asList( propertyName, - propertyDescriptor.getDescription(property), + propertyDescriptor.getDescription(property, propertyName), Boolean.toString(property.getRequired()), typeSchema(propertyType), PropertyUtils.getDefaultValue(property)); @@ -141,10 +153,36 @@ public abstract class MarkupDocument { this.type = type; } - public String getDescription(Property property) { + public String getDescription(Property property, String propertyName) { return defaultString(property.getDescription()); } } + public void sectionTitleLevel(int level, String title, String anchor, MarkupDocBuilder docBuilder) { + if (anchor != null) + docBuilder.textLine(MarkupDocBuilderUtils.anchor(anchor, this.markupLanguage)); + switch (level) { + case 1: + docBuilder.sectionTitleLevel1(title); + break; + case 2: + docBuilder.sectionTitleLevel2(title); + break; + case 3: + docBuilder.sectionTitleLevel3(title); + break; + case 4: + docBuilder.sectionTitleLevel4(title); + break; + case 5: + if (anchor == null) + docBuilder.textLine(MarkupDocBuilderUtils.anchor(title, this.markupLanguage)); + docBuilder.boldTextLine(title); + break; + default: + throw new RuntimeException("Illegal section level : " + level); + } + + } } 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 447b5e13..efee1069 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 @@ -22,6 +22,8 @@ import com.google.common.base.Optional; import com.google.common.collect.Multimap; import io.github.robwin.swagger2markup.GroupBy; 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.ParameterUtils; import io.github.robwin.swagger2markup.utils.PropertyUtils; @@ -62,6 +64,8 @@ public class PathsDocument extends MarkupDocument { private final String CURL_EXAMPLE_FILE_NAME; private final String DESCRIPTION_FILE_NAME; private final String PARAMETER; + private final String DEFINITIONS; + private boolean examplesEnabled; private String examplesFolderPath; @@ -88,6 +92,7 @@ public class PathsDocument extends MarkupDocument { CURL_EXAMPLE_FILE_NAME = labels.getString("curl_example_file_name"); DESCRIPTION_FILE_NAME = labels.getString("description_file_name"); PARAMETER = labels.getString("parameter"); + DEFINITIONS = labels.getString("definitions"); this.pathsGroupedBy = swagger2MarkupConfig.getPathsGroupedBy(); if(isNotBlank(swagger2MarkupConfig.getExamplesFolderPath())){ @@ -180,14 +185,17 @@ public class PathsDocument extends MarkupDocument { */ private void path(String methodAndPath, Operation operation) { if(operation != null){ + List localDefinitions = new ArrayList<>(); + pathTitle(methodAndPath, operation); descriptionSection(operation); - parametersSection(operation); - responsesSection(operation); + localDefinitions.addAll(parametersSection(operation)); + localDefinitions.addAll(responsesSection(operation)); consumesSection(operation); producesSection(operation); tagsSection(operation); examplesSection(operation); + localDefinitionsSection(localDefinitions); } } @@ -276,8 +284,9 @@ public class PathsDocument extends MarkupDocument { } } - private void parametersSection(Operation operation) { + private List parametersSection(Operation operation) { List parameters = operation.getParameters(); + List localDefinitions = new ArrayList<>(); if(CollectionUtils.isNotEmpty(parameters)){ List headerAndContent = new ArrayList<>(); // Table header row @@ -285,6 +294,14 @@ public class PathsDocument extends MarkupDocument { headerAndContent.add(join(header, DELIMITER)); for(Parameter parameter : parameters){ Type type = ParameterUtils.getType(parameter); + if (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); // Table content row List content = Arrays.asList( @@ -299,6 +316,8 @@ public class PathsDocument extends MarkupDocument { addPathSectionTitle(PARAMETERS); this.markupDocBuilder.tableWithHeaderRow(headerAndContent); } + + return localDefinitions; } /** @@ -466,8 +485,9 @@ public class PathsDocument extends MarkupDocument { return Optional.absent(); } - private void responsesSection(Operation operation) { + private List responsesSection(Operation operation) { Map responses = operation.getResponses(); + List localDefinitions = new ArrayList<>(); if(MapUtils.isNotEmpty(responses)){ List csvContent = new ArrayList<>(); csvContent.add(HTTP_CODE_COLUMN + DELIMITER + DESCRIPTION_COLUMN + DELIMITER + SCHEMA_COLUMN); @@ -476,6 +496,14 @@ public class PathsDocument extends MarkupDocument { if(response.getSchema() != null){ Property property = response.getSchema(); Type type = PropertyUtils.getType(property); + if (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)); }else{ csvContent.add(entry.getKey() + DELIMITER + response.getDescription() + DELIMITER + "No Content"); @@ -484,6 +512,22 @@ public class PathsDocument extends MarkupDocument { addPathSectionTitle(RESPONSES); this.markupDocBuilder.tableWithHeaderRow(csvContent); } + return localDefinitions; } + private void localDefinitionsSection(List definitions) { + if(CollectionUtils.isNotEmpty(definitions)){ + addPathSectionTitle(DEFINITIONS); + + for (Type definition: definitions) { + if(pathsGroupedBy.equals(GroupBy.AS_IS)){ + sectionTitleLevel(4, definition.getName(), definition.getUniqueName(), this.markupDocBuilder); + }else{ + sectionTitleLevel(5, definition.getName(), definition.getUniqueName(), this.markupDocBuilder); + } + typeProperties(definition, new PropertyDescriptor(definition), this.markupDocBuilder); + } + } + + } } diff --git a/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java b/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java index 4ae76482..36731c33 100644 --- a/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java +++ b/src/main/java/io/github/robwin/swagger2markup/type/ObjectType.java @@ -3,7 +3,6 @@ package io.github.robwin.swagger2markup.type; import io.github.robwin.markup.builder.MarkupLanguage; import io.swagger.models.properties.Property; -import java.util.List; import java.util.Map; public class ObjectType extends Type { diff --git a/src/main/java/io/github/robwin/swagger2markup/type/RefType.java b/src/main/java/io/github/robwin/swagger2markup/type/RefType.java index 665a1695..f6a41441 100644 --- a/src/main/java/io/github/robwin/swagger2markup/type/RefType.java +++ b/src/main/java/io/github/robwin/swagger2markup/type/RefType.java @@ -1,6 +1,7 @@ package io.github.robwin.swagger2markup.type; import io.github.robwin.markup.builder.MarkupLanguage; +import io.github.robwin.swagger2markup.utils.MarkupDocBuilderUtils; public class RefType extends Type { @@ -8,13 +9,12 @@ public class RefType extends Type { super(name); } + public RefType(Type type) { + super(type.name, type.uniqueName); + } + @Override public String displaySchema(MarkupLanguage language) { - switch (language) { - case ASCIIDOC: - return "<<" + getName() + ">>"; - default: - return getName(); - } + return MarkupDocBuilderUtils.crossReference(getName(), getUniqueName(), language); } } diff --git a/src/main/java/io/github/robwin/swagger2markup/type/Type.java b/src/main/java/io/github/robwin/swagger2markup/type/Type.java index 53c5a94c..2660cccd 100644 --- a/src/main/java/io/github/robwin/swagger2markup/type/Type.java +++ b/src/main/java/io/github/robwin/swagger2markup/type/Type.java @@ -6,13 +6,20 @@ import org.apache.commons.lang3.Validate; public abstract class Type { protected String name; + protected String uniqueName; - public Type() { + public Type(String name, String uniqueName) { + Validate.notBlank(name); + + this.name = name; + this.uniqueName = uniqueName; } public Type(String name) { - Validate.notBlank(name); + this(name, name); + } + public void setName(String name) { this.name = name; } @@ -20,5 +27,13 @@ public abstract class Type { return name; } + public String getUniqueName() { + return uniqueName; + } + + public void setUniqueName(String uniqueName) { + this.uniqueName = uniqueName; + } + public abstract String displaySchema(MarkupLanguage language); } diff --git a/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java b/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java new file mode 100644 index 00000000..f3038d76 --- /dev/null +++ b/src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java @@ -0,0 +1,41 @@ +package io.github.robwin.swagger2markup.utils; + +import io.github.robwin.markup.builder.MarkupDocBuilder; +import io.github.robwin.markup.builder.MarkupLanguage; + +/* + * FIXME : this code should go to markup-document-builder project + */ +public class MarkupDocBuilderUtils { + + public static String normalizeAnchor(String anchor) { + return anchor.replaceAll("[^0-9a-zA-Z]", "_"); + } + + public static String anchor(String text, MarkupLanguage language) { + switch (language) { + case ASCIIDOC: + return "[[" + normalizeAnchor(text) + "]]"; + default: + return ""; + } + } + + public static String crossReference(String text, String anchor, MarkupLanguage language) { + switch (language) { + case ASCIIDOC: + String normalizedAnchor = normalizeAnchor(anchor); + if (text == null && !anchor.equals(normalizedAnchor)) + text = anchor; + if (text == null) + return "<<" + normalizedAnchor + ">>"; + else + return "<<" + normalizedAnchor + "," + text + ">>"; + default: + if (text == null) + return anchor; + else + return text; + } + } +}