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

Added .withInlineSchemaDepthLevel to converter configuration (default: 0 = disable feature)

Browse Source 
Added inline schema support for global definitions.
Relayout inlineSchema feature : no mode distinct Definitions section in Paths, inline types are displayed right after each original type. This is for consistency with global definitions.
This commit is contained in:
Hugo de Paix de Coeur
2016-02-02 11:45:22 +01:00
parent b2f4229f70
commit ead3e0bc22
6 changed files with 77 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

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

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

@@ -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<String, Model> definitions, String definitionName, Model model, MarkupDocBuilder docBuilder){
Map<String, Property> properties = getAllProperties(definitions, model);
Type type = new ObjectType(definitionName, properties);
typeProperties(type, new DefinitionPropertyDescriptor(type), docBuilder);
List<Type> localDefinitions = typeProperties(type, inlineSchemaDepthLevel, new PropertyDescriptor(type), docBuilder);
inlineDefinitions(localDefinitions, inlineSchemaDepthLevel - 1, docBuilder);
}
private Map<String, Property> getAllProperties(Map<String, Model> definitions, Model model) {
@@ -341,4 +347,16 @@ public class DefinitionsDocument extends MarkupDocument {
}
}
}
private void inlineDefinitions(List<Type> definitions, int depth, MarkupDocBuilder docBuilder) {
if(CollectionUtils.isNotEmpty(definitions)){
for (Type definition: definitions) {
MarkupDocBuilderUtils.sectionTitleLevel(5, definition.getName(), definition.getUniqueName(), this.markupLanguage, docBuilder);
List<Type> localDefinitions = typeProperties(definition, depth, new DefinitionPropertyDescriptor(definition), docBuilder);
for (Type localDefinition : localDefinitions)
inlineDefinitions(Arrays.asList(localDefinition), depth - 1, docBuilder);
}
}
}
}

16
src/main/java/io/github/robwin/swagger2markup/builder/document/MarkupDocument.java
View File

@@ -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<Type> typeProperties(Type type, int depth, PropertyDescriptor propertyDescriptor, MarkupDocBuilder docBuilder) {
List<Type> localDefinitions = new ArrayList<>();
if (type instanceof ObjectType) {
ObjectType objectType = (ObjectType) type;
List<String> 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<String> content = Arrays.asList(
propertyName,
propertyDescriptor.getDescription(property, propertyName),
@@ -139,6 +151,8 @@ public abstract class MarkupDocument {
docBuilder.tableWithHeaderRow(headerAndContent);
}
}
return localDefinitions;
}
public class PropertyDescriptor {

27
src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java
View File

@@ -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<Type> 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<Type> definitions) {
private void inlineDefinitions(List<Type> 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<Type> localDefinitions = typeProperties(definition, depth, new PropertyDescriptor(definition), this.markupDocBuilder);
for (Type localDefinition : localDefinitions)
inlineDefinitions(Arrays.asList(localDefinition), depth - 1);
}
}

10
src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java
View File

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

5
src/main/java/io/github/robwin/swagger2markup/utils/MarkupDocBuilderUtils.java
View File

@@ -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);
}