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

Merge remote-tracking branch 'origin/master'

Browse Source
This commit is contained in:
Robert Winkler
2016-04-05 15:05:53 +02:00
parent e959c9ed59 1965110df9
commit aaac78f985
21 changed files with 28 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

22
src/docs/asciidoc/usage_guide.adoc
View File

@@ -114,7 +114,7 @@ Configuration parameters may be loaded from the following sources using Apache C
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupConfigFromCommonsConfiguration]
----
1. Create an Apache Commons `Configuraton` object using the proper ConfigurationBuilder.
1. Create an Apache Commons `Configuration` object using the proper ConfigurationBuilder.
2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.
=== Swagger2Markup properties
@@ -136,7 +136,7 @@ The following tables list all available properties of Swagger2Markup:
|swagger2markup.swaggerMarkupLanguage| Specifies the markup language used in Swagger descriptions. | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | MARKDOWN
|swagger2markup.pathsGroupedBy| Specifies how the paths should be grouped | AS_IS, TAGS | AS_IS
|swagger2markup.outputLanguage| Specifies the language of the labels | EN, DE, FR, RU | EN
|swagger2markup.lineSeparator| Specifies the line separator which should be used | UNIX, WINDOWS, MAC | System-dependent
|swagger2markup.lineSeparator| Specifies the line separator which should be used | UNIX, WINDOWS, MAC | <System-dependent>
|swagger2markup.generatedExamplesEnabled| Specifies if HTTP request and response examples should be generated | true, false | false
|===
@@ -146,7 +146,7 @@ The following tables list all available properties of Swagger2Markup:
|Name | Description | Possible Values | Default
|swagger2markup.tagOrderBy| Specifies the order of global tags | AS_IS, NATURAL, CUSTOM | NATURAL
|swagger2markup.operationOrderBy| Specifies the order of path operations | AS_IS, NATURAL, CUSTOM | NATURAL
|swagger2markup.definitionOrderBy| Specifies the order of definitons | AS_IS, NATURAL, CUSTOM | NATURAL
|swagger2markup.definitionOrderBy| Specifies the order of definitions | AS_IS, NATURAL, CUSTOM | NATURAL
|swagger2markup.parameterOrderBy| Specifies the order of operation parameters | AS_IS, NATURAL, CUSTOM | NATURAL
|swagger2markup.propertyOrderBy | Specifies the order of definition properties | AS_IS, NATURAL, CUSTOM | NATURAL
|swagger2markup.responseOrderBy| Specifies the order of responses | AS_IS, NATURAL, CUSTOM | NATURAL
@@ -156,10 +156,10 @@ The following tables list all available properties of Swagger2Markup:
.Properties which configure document file names
|===
|Name | Description | Possible Values | Default
|swagger2markup.overviewDocument| Specifies the file name of the overview document | Any String | overview
|swagger2markup.pathsDocument| Specifies the file name of the paths document | Any String | paths
|swagger2markup.definitionsDocument| Specifies the file name of the definitions document | Any String | definitions
|swagger2markup.securityDocument| Specifies the file name of the security document | Any String | security
|swagger2markup.overviewDocument| Specifies the file name of the overview document | Any String | "overview"
|swagger2markup.pathsDocument| Specifies the file name of the paths document | Any String | "paths"
|swagger2markup.definitionsDocument| Specifies the file name of the definitions document | Any String | "definitions"
|swagger2markup.securityDocument| Specifies the file name of the security document | Any String | "security"
|===
[options="header"]
@@ -168,16 +168,16 @@ The following tables list all available properties of Swagger2Markup:
|Name | Description | Possible Values | Default
|swagger2markup.separatedDefinitionsEnabled| In addition to the Definitions file, also create separate definition files for each model definition | true, false | false
|swagger2markup.separatedOperationsEnabled| In addition to the Paths file, also create separate operation files for each operation | true, false | false
|swagger2markup.separatedOperationsFolder| Specifies the target folder path for definition files| Any valid path | operations
|swagger2markup.separatedDefinitionsFolder| Specifies the target folder path for operation files | Any valid path | definitions
|swagger2markup.separatedOperationsFolder| Specifies the target folder path for definition files| Any valid folder name | "operations"
|swagger2markup.separatedDefinitionsFolder| Specifies the target folder path for operation files | Any valid folder name | "definitions"
|===
[options="header"]
.Properties which configure interdocument cross references
.Properties which configure inter-document cross references
|===
|Name | Description | Possible Values | Default
|swagger2markup.interDocumentCrossReferencesEnabled| Enable use of inter-document cross-references when needed | true, false | false
|swagger2markup.interDocumentCrossReferencesPrefix| Specifies a prefix for all inter-document cross-references | Any String |
|swagger2markup.interDocumentCrossReferencesPrefix| Specifies a prefix for all inter-document cross-references for advanced usage | Any String |
|swagger2markup.anchorPrefix| Optionally prefix all anchors for uniqueness | Any String |
|===

21
src/main/java/io/github/swagger2markup/Swagger2MarkupConfig.java
View File

@@ -20,7 +20,6 @@ import io.github.swagger2markup.markup.builder.MarkupLanguage;
import io.github.swagger2markup.model.PathOperation;
import io.swagger.models.parameters.Parameter;
import java.net.URI;
import java.util.Comparator;
/**
@@ -44,26 +43,6 @@ public interface Swagger2MarkupConfig {
*/
boolean isGeneratedExamplesEnabled();
/**
* Include hand-written descriptions into the Paths document.
*/
boolean isOperationDescriptionsEnabled();
/**
* Hand-written operation descriptions URI.
*/
URI getOperationDescriptionsUri();
/**
* Include hand-written descriptions into the Definitions document.
*/
boolean isDefinitionDescriptionsEnabled();
/**
* Hand-written definition descriptions URI.
*/
URI getDefinitionDescriptionsUri();
/**
* In addition to the Definitions file, also create separate definition files for each model definition.
*/

2
src/main/java/io/github/swagger2markup/Swagger2MarkupProperties.java
View File

@@ -40,8 +40,6 @@ public class Swagger2MarkupProperties {
public static final String MARKUP_LANGUAGE = PROPERTIES_PREFIX + ".markupLanguage";
public static final String SWAGGER_MARKUP_LANGUAGE = PROPERTIES_PREFIX + ".swaggerMarkupLanguage";
public static final String GENERATED_EXAMPLES_ENABLED = PROPERTIES_PREFIX + ".generatedExamplesEnabled";
public static final String OPERATION_DESCRIPTIONS_ENABLED = PROPERTIES_PREFIX + ".operationDescriptionsEnabled";
public static final String DEFINITION_DESCRIPTIONS_ENABLED = PROPERTIES_PREFIX + ".definitionDescriptionsEnabled";
public static final String SEPARATED_DEFINITIONS_ENABLED = PROPERTIES_PREFIX + ".separatedDefinitionsEnabled";
public static final String SEPARATED_OPERATIONS_ENABLED = PROPERTIES_PREFIX + ".separatedOperationsEnabled";
public static final String PATHS_GROUPED_BY = PROPERTIES_PREFIX + ".pathsGroupedBy";

93
src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java
View File

@@ -32,7 +32,6 @@ import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.net.URI;
import java.nio.file.Path;
import java.util.Comparator;
import java.util.Map;
import java.util.Optional;
@@ -103,8 +102,6 @@ public class Swagger2MarkupConfigBuilder {
config.markupLanguage = swagger2MarkupProperties.getRequiredMarkupLanguage(MARKUP_LANGUAGE);
config.swaggerMarkupLanguage = swagger2MarkupProperties.getRequiredMarkupLanguage(SWAGGER_MARKUP_LANGUAGE);
config.generatedExamplesEnabled = swagger2MarkupProperties.getRequiredBoolean(GENERATED_EXAMPLES_ENABLED);
config.operationDescriptionsEnabled = swagger2MarkupProperties.getRequiredBoolean(OPERATION_DESCRIPTIONS_ENABLED);
config.definitionDescriptionsEnabled = swagger2MarkupProperties.getRequiredBoolean(DEFINITION_DESCRIPTIONS_ENABLED);
config.separatedDefinitionsEnabled = swagger2MarkupProperties.getRequiredBoolean(SEPARATED_DEFINITIONS_ENABLED);
config.separatedOperationsEnabled = swagger2MarkupProperties.getRequiredBoolean(SEPARATED_OPERATIONS_ENABLED);
config.pathsGroupedBy = swagger2MarkupProperties.getGroupBy(PATHS_GROUPED_BY);
@@ -210,76 +207,6 @@ public class Swagger2MarkupConfigBuilder {
return this;
}
/**
* Include hand-written descriptions into the Paths document.
*
* @param operationDescriptionsUri the URI to the folder where the description documents reside.
* @return this builder
*/
public Swagger2MarkupConfigBuilder withOperationDescriptions(URI operationDescriptionsUri) {
Validate.notNull(operationDescriptionsUri, "%s must not be null", "operationDescriptionsUri");
config.operationDescriptionsEnabled = true;
config.operationDescriptionsUri = operationDescriptionsUri;
return this;
}
/**
* Include hand-written descriptions into the Paths document.
*
* @param operationDescriptionsPath the path to the folder where the description documents reside.
* @return this builder
*/
public Swagger2MarkupConfigBuilder withOperationDescriptions(Path operationDescriptionsPath) {
Validate.notNull(operationDescriptionsPath, "%s must not be null", "operationDescriptionsPath");
return withOperationDescriptions(operationDescriptionsPath.toUri());
}
/**
* Include hand-written descriptions into the Paths document.<br>
* Use default URI.
*
* @return this builder
*/
public Swagger2MarkupConfigBuilder withOperationDescriptions() {
config.operationDescriptionsEnabled = true;
return this;
}
/**
* Include hand-written descriptions into the Definitions document.
*
* @param definitionDescriptionsUri the URI to the folder where the description documents reside.
* @return this builder
*/
public Swagger2MarkupConfigBuilder withDefinitionDescriptions(URI definitionDescriptionsUri) {
Validate.notNull(definitionDescriptionsUri, "%s must not be null", "definitionDescriptionsUri");
config.definitionDescriptionsEnabled = true;
config.definitionDescriptionsUri = definitionDescriptionsUri;
return this;
}
/**
* Include hand-written descriptions into the Definitions document.
*
* @param definitionDescriptionsPath the path to the folder where the description documents reside.
* @return this builder
*/
public Swagger2MarkupConfigBuilder withDefinitionDescriptions(Path definitionDescriptionsPath) {
Validate.notNull(definitionDescriptionsPath, "%s must not be null", "definitionDescriptionsPath");
return withDefinitionDescriptions(definitionDescriptionsPath.toUri());
}
/**
* Include hand-written descriptions into the Definitions document.<br>
* Use default URI.
*
* @return this builder
*/
public Swagger2MarkupConfigBuilder withDefinitionDescriptions() {
config.definitionDescriptionsEnabled = true;
return this;
}
/**
* In addition to the Definitions file, also create separate definition files for each model definition.
*
@@ -622,26 +549,6 @@ public class Swagger2MarkupConfigBuilder {
return generatedExamplesEnabled;
}
@Override
public boolean isOperationDescriptionsEnabled() {
return operationDescriptionsEnabled;
}
@Override
public URI getOperationDescriptionsUri() {
return operationDescriptionsUri;
}
@Override
public boolean isDefinitionDescriptionsEnabled() {
return definitionDescriptionsEnabled;
}
@Override
public URI getDefinitionDescriptionsUri() {
return definitionDescriptionsUri;
}
@Override
public boolean isSeparatedDefinitionsEnabled() {
return separatedDefinitionsEnabled;

87
src/main/java/io/github/swagger2markup/internal/document/builder/DefinitionsDocumentBuilder.java
View File

@@ -15,7 +15,6 @@
*/
package io.github.swagger2markup.internal.document.builder;
import com.google.common.base.Optional;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.Swagger2MarkupExtensionRegistry;
import io.github.swagger2markup.internal.document.MarkupDocument;
@@ -26,17 +25,12 @@ import io.github.swagger2markup.internal.utils.ModelUtils;
import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
import io.github.swagger2markup.spi.DefinitionsDocumentExtension;
import io.swagger.models.Model;
import io.swagger.models.properties.Property;
import org.apache.commons.collections4.CollectionUtils;
import org.apache.commons.collections4.MapUtils;
import org.apache.commons.io.IOUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.Validate;
import java.io.File;
import java.io.IOException;
import java.io.Reader;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.*;
@@ -78,15 +72,6 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
}};
TYPE_COLUMN = labels.getString("type_column");
if (config.isDefinitionDescriptionsEnabled()) {
if (logger.isDebugEnabled()) {
logger.debug("Include hand-written definition descriptions is enabled.");
}
} else {
if (logger.isDebugEnabled()) {
logger.debug("Include hand-written definition descriptions is disabled.");
}
}
if (config.isSeparatedDefinitionsEnabled()) {
if (logger.isDebugEnabled()) {
logger.debug("Create separated definition files is enabled.");
@@ -207,7 +192,7 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
private void buildDefinition(String definitionName, Model model, MarkupDocBuilder docBuilder) {
buildDefinitionTitle(definitionName, definitionName, docBuilder);
applyDefinitionsDocumentExtension(new Context(Position.DEFINITION_BEGIN, docBuilder, definitionName, model));
buildDescriptionParagraph(definitionName, model, docBuilder);
buildDescriptionParagraph(model, docBuilder);
inlineDefinitions(typeSection(definitionName, model, docBuilder), definitionName, config.getInlineSchemaDepthLevel(), docBuilder);
applyDefinitionsDocumentExtension(new Context(Position.DEFINITION_END, docBuilder, definitionName, model));
}
@@ -232,31 +217,7 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
private void buildDefinitionTitle(String title, String anchor, MarkupDocBuilder docBuilder) {
docBuilder.sectionTitleWithAnchorLevel2(title, anchor);
}
/**
* Override Property description functor for definitions.
* This implementation handles optional handwritten descriptions.
*/
private class DefinitionPropertyDescriptor extends PropertyDescriptor {
public DefinitionPropertyDescriptor(Type type) {
super(type);
}
@Override
public String getDescription(Property property, String propertyName) {
if (config.isDefinitionDescriptionsEnabled()) {
Optional<String> description = handWrittenDefinitionDescription(new File(normalizeName(type.getName()), normalizeName(propertyName)).toString(), DESCRIPTION_FILE_NAME);
if (description.isPresent()) {
return description.get();
} else {
return defaultString(property.getDescription());
}
} else {
return defaultString(property.getDescription());
}
}
}
/**
* Builds the type informations of a definition
@@ -294,7 +255,7 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
if (StringUtils.isNotBlank(typeInfosString))
docBuilder.paragraph(typeInfosString, true);
localDefinitions.addAll(buildPropertiesTable(((ObjectType) modelType).getProperties(), definitionName, 1, new PropertyDescriptor(modelType), new DefinitionDocumentResolverFromDefinition(), docBuilder));
localDefinitions.addAll(buildPropertiesTable(((ObjectType) modelType).getProperties(), definitionName, 1, new DefinitionDocumentResolverFromDefinition(), docBuilder));
} else if (modelType != null) {
MarkupDocBuilder typeInfos = docBuilder.copy(false);
typeInfos.italicText(TYPE_COLUMN).textLine(" : " + modelType.displaySchema(docBuilder));
@@ -305,17 +266,8 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
return localDefinitions;
}
private void buildDescriptionParagraph(String definitionName, Model model, MarkupDocBuilder docBuilder) {
if (config.isDefinitionDescriptionsEnabled()) {
Optional<String> description = handWrittenDefinitionDescription(normalizeName(definitionName), DESCRIPTION_FILE_NAME);
if (description.isPresent()) {
buildDescriptionParagraph(description.get(), docBuilder);
} else {
modelDescription(model, docBuilder);
}
} else {
modelDescription(model, docBuilder);
}
private void buildDescriptionParagraph(Model model, MarkupDocBuilder docBuilder) {
modelDescription(model, docBuilder);
}
private void modelDescription(Model model, MarkupDocBuilder docBuilder) {
@@ -325,33 +277,6 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
}
}
/**
* Reads a hand-written description
*
* @param descriptionFolder the name of the folder where the description file resides
* @param descriptionFileName the name of the description file
* @return the content of the file
*/
private Optional<String> handWrittenDefinitionDescription(String descriptionFolder, String descriptionFileName) {
for (String fileNameExtension : config.getMarkupLanguage().getFileNameExtensions()) {
URI contentUri = config.getDefinitionDescriptionsUri().resolve(descriptionFolder).resolve(descriptionFileName + fileNameExtension);
try (Reader reader = io.github.swagger2markup.utils.IOUtils.uriReader(contentUri)) {
if (logger.isInfoEnabled()) {
logger.info("Definition description content processed {}", contentUri);
}
return Optional.of(IOUtils.toString(reader).trim());
} catch (IOException e) {
if (logger.isDebugEnabled()) {
logger.debug("Failed to read Operation description content {} > {}", contentUri, e.getMessage());
}
}
}
return Optional.absent();
}
/**
* Builds the title of an inline schema.
* Inline definitions should never been referenced in TOC because they have no real existence, so they are just text.
@@ -378,7 +303,7 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
if (CollectionUtils.isNotEmpty(definitions)) {
for (ObjectType definition : definitions) {
addInlineDefinitionTitle(definition.getName(), definition.getUniqueName(), docBuilder);
List<ObjectType> localDefinitions = buildPropertiesTable(definition.getProperties(), uniquePrefix, depth, new DefinitionPropertyDescriptor(definition), new DefinitionDocumentResolverFromDefinition(), docBuilder);
List<ObjectType> localDefinitions = buildPropertiesTable(definition.getProperties(), uniquePrefix, depth, new DefinitionDocumentResolverFromDefinition(), docBuilder);
for (ObjectType localDefinition : localDefinitions)
inlineDefinitions(Collections.singletonList(localDefinition), uniquePrefix, depth - 1, docBuilder);
}

22
src/main/java/io/github/swagger2markup/internal/document/builder/MarkupDocumentBuilder.java
View File

@@ -108,12 +108,11 @@ public abstract class MarkupDocumentBuilder {
* @param properties properties to display
* @param uniquePrefix unique prefix to prepend to inline object names to enforce unicity
* @param depth current inline schema object depth
* @param propertyDescriptor property descriptor to apply to properties
* @param definitionDocumentResolver definition document resolver to apply to property type cross-reference
* @param docBuilder the docbuilder do use for output
* @return a list of inline schemas referenced by some properties, for later display
*/
protected List<ObjectType> buildPropertiesTable(Map<String, Property> properties, String uniquePrefix, int depth, PropertyDescriptor propertyDescriptor, DefinitionDocumentResolver definitionDocumentResolver, MarkupDocBuilder docBuilder) {
protected List<ObjectType> buildPropertiesTable(Map<String, Property> properties, String uniquePrefix, int depth, DefinitionDocumentResolver definitionDocumentResolver, MarkupDocBuilder docBuilder) {
List<ObjectType> localDefinitions = new ArrayList<>();
List<List<String>> cells = new ArrayList<>();
List<MarkupTableColumn> cols = Arrays.asList(
@@ -134,7 +133,7 @@ public abstract class MarkupDocumentBuilder {
propertyType.setUniqueName(uniquePrefix + " " + propertyName);
localDefinitions.add((ObjectType) propertyType);
propertyType = new RefType((ObjectType) propertyType);
propertyType = new RefType(propertyType);
}
}
@@ -142,7 +141,7 @@ public abstract class MarkupDocumentBuilder {
List<String> content = Arrays.asList(
propertyName,
swaggerMarkupDescription(propertyDescriptor.getDescription(property, propertyName)),
swaggerMarkupDescription(defaultString(property.getDescription())),
Boolean.toString(property.getRequired()),
propertyType.displaySchema(docBuilder),
PropertyUtils.getDefaultValue(property),
@@ -174,21 +173,6 @@ public abstract class MarkupDocumentBuilder {
}
}
/**
* A functor to return descriptions for a given property
*/
class PropertyDescriptor {
protected Type type;
public PropertyDescriptor(Type type) {
this.type = type;
}
public String getDescription(Property property, String propertyName) {
return defaultString(property.getDescription());
}
}
/**
* Default {@code DefinitionDocumentResolver} functor
*/

99
src/main/java/io/github/swagger2markup/internal/document/builder/PathsDocumentBuilder.java
View File

@@ -39,15 +39,11 @@ import io.swagger.models.properties.Property;
import io.swagger.util.Json;
import org.apache.commons.collections4.CollectionUtils;
import org.apache.commons.collections4.MapUtils;
import org.apache.commons.io.IOUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.Validate;
import org.apache.commons.lang3.text.WordUtils;
import java.io.File;
import java.io.IOException;
import java.io.Reader;
import java.net.URI;
import java.nio.charset.StandardCharsets;
import java.util.*;
@@ -117,15 +113,6 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
logger.debug("Include examples is disabled.");
}
}
if (config.isOperationDescriptionsEnabled()) {
if (logger.isDebugEnabled()) {
logger.debug("Include hand-written operation descriptions is enabled.");
}
} else {
if (logger.isDebugEnabled()) {
logger.debug("Include hand-written operation descriptions is disabled.");
}
}
if (config.isSeparatedOperationsEnabled()) {
if (logger.isDebugEnabled()) {
@@ -411,19 +398,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
* @param docBuilder the docbuilder do use for output
*/
private void buildDescriptionSection(PathOperation operation, MarkupDocBuilder docBuilder) {
if (config.isOperationDescriptionsEnabled()) {
Optional<String> description = handWrittenOperationDescription(normalizeName(operation.getId()), DESCRIPTION_FILE_NAME);
if (!description.isPresent())
description = handWrittenOperationDescription(normalizeName(operation.getTitle()), DESCRIPTION_FILE_NAME);
if (description.isPresent()) {
operationDescription(description.get(), docBuilder);
} else {
operationDescription(operation.getOperation().getDescription(), docBuilder);
}
} else {
operationDescription(operation.getOperation().getDescription(), docBuilder);
}
operationDescription(operation.getOperation().getDescription(), docBuilder);
}
private void operationDescription(String description, MarkupDocBuilder docBuilder) {
@@ -479,7 +454,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
type.setName(localTypeName);
type.setUniqueName(operation.getId() + " " + localTypeName);
localDefinitions.add((ObjectType) type);
type = new RefType((ObjectType) type);
type = new RefType(type);
}
}
String parameterType = WordUtils.capitalize(parameter.getIn());
@@ -487,7 +462,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
List<String> content = Arrays.asList(
parameterType,
parameter.getName(),
swaggerMarkupDescription(parameterDescription(operation, parameter)),
swaggerMarkupDescription(defaultString(parameter.getDescription())),
Boolean.toString(parameter.getRequired()),
type.displaySchema(markupDocBuilder),
ParameterUtils.getDefaultValue(parameter));
@@ -533,7 +508,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
docBuilder.paragraph(typeInfos.toString(), true);
if (type instanceof ObjectType) {
localDefinitions.addAll(buildPropertiesTable(((ObjectType) type).getProperties(), operation.getId(), config.getInlineSchemaDepthLevel(), new PropertyDescriptor(type), new DefinitionDocumentResolverFromOperation(), docBuilder));
localDefinitions.addAll(buildPropertiesTable(((ObjectType) type).getProperties(), operation.getId(), config.getInlineSchemaDepthLevel(), new DefinitionDocumentResolverFromOperation(), docBuilder));
}
}
}
@@ -543,40 +518,6 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
return localDefinitions;
}
/**
* Retrieves the description of a parameter, or otherwise an empty String.
* If hand-written descriptions exist, it tries to load the description from a file.
* If the file cannot be read, the description of the parameter is returned.
* Operation folder search order :
* - normalizeOperationFileName(operation.operationId)
* - then, normalizeOperationFileName(operation.method + " " + operation.path)
* - then, normalizeOperationFileName(operation.summary)
*
* @param operation the Swagger Operation
* @param parameter the Swagger Parameter
* @return the description of a parameter.
*/
private String parameterDescription(final PathOperation operation, Parameter parameter) {
if (config.isOperationDescriptionsEnabled()) {
final String parameterName = parameter.getName();
if (isNotBlank(parameterName)) {
Optional<String> description = handWrittenOperationDescription(new File(normalizeName(operation.getId()), parameterName).getPath(), DESCRIPTION_FILE_NAME);
if (!description.isPresent())
description = handWrittenOperationDescription(new File(normalizeName(operation.getTitle()), parameterName).getPath(), DESCRIPTION_FILE_NAME);
if (description.isPresent()) {
return description.get();
} else {
return defaultString(parameter.getDescription());
}
} else {
return defaultString(parameter.getDescription());
}
} else {
return defaultString(parameter.getDescription());
}
}
private void buildConsumesSection(PathOperation operation, MarkupDocBuilder docBuilder) {
List<String> consumes = operation.getOperation().getConsumes();
if (CollectionUtils.isNotEmpty(consumes)) {
@@ -674,32 +615,6 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
}
}
/**
* Reads a hand-written description
*
* @param descriptionFolder the name of the folder where the description file resides
* @param descriptionFileName the name of the description file
* @return the content of the file
*/
private Optional<String> handWrittenOperationDescription(String descriptionFolder, String descriptionFileName) {
for (String fileNameExtension : config.getMarkupLanguage().getFileNameExtensions()) {
URI contentUri = config.getOperationDescriptionsUri().resolve(descriptionFolder).resolve(descriptionFileName + fileNameExtension);
try (Reader reader = io.github.swagger2markup.utils.IOUtils.uriReader(contentUri)) {
if (logger.isInfoEnabled()) {
logger.info("Operation description content processed {}", contentUri);
}
return Optional.of(IOUtils.toString(reader).trim());
} catch (IOException e) {
if (logger.isDebugEnabled()) {
logger.debug("Failed to read Operation description content {} > {}", contentUri, e.getMessage());
}
}
}
return Optional.absent();
}
private List<ObjectType> buildResponsesSection(PathOperation operation, MarkupDocBuilder docBuilder) {
Map<String, Response> responses = operation.getOperation().getResponses();
List<ObjectType> localDefinitions = new ArrayList<>();
@@ -733,7 +648,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
type.setName(localTypeName);
type.setUniqueName(operation.getId() + " " + localTypeName);
localDefinitions.add((ObjectType) type);
type = new RefType((ObjectType) type);
type = new RefType(type);
}
}
cells.add(Arrays.asList(responseName, swaggerMarkupDescription(response.getDescription()), type.displaySchema(markupDocBuilder)));
@@ -751,7 +666,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
Property property = header.getValue();
Type propertyType = PropertyUtils.getType(property, null);
responseHeaderCells.add(Arrays.asList(header.getKey(),
swaggerMarkupDescription(property.getDescription()),
swaggerMarkupDescription(defaultString(property.getDescription())),
propertyType.displaySchema(markupDocBuilder),
PropertyUtils.getDefaultValue(property)));
}
@@ -793,7 +708,7 @@ public class PathsDocumentBuilder extends MarkupDocumentBuilder {
for (ObjectType definition : definitions) {
addInlineDefinitionTitle(definition.getName(), definition.getUniqueName(), docBuilder);
List<ObjectType> localDefinitions = buildPropertiesTable(definition.getProperties(), uniquePrefix, depth, new PropertyDescriptor(definition), new DefinitionDocumentResolverFromOperation(), docBuilder);
List<ObjectType> localDefinitions = buildPropertiesTable(definition.getProperties(), uniquePrefix, depth, new DefinitionDocumentResolverFromOperation(), docBuilder);
for (ObjectType localDefinition : localDefinitions)
inlineDefinitions(Collections.singletonList(localDefinition), uniquePrefix, depth - 1, docBuilder);
}

2
src/main/resources/io/github/swagger2markup/config/default.properties
View File

@@ -1,8 +1,6 @@
swagger2markup.markupLanguage=ASCIIDOC
swagger2markup.swaggerMarkupLanguage=MARKDOWN
swagger2markup.generatedExamplesEnabled=false
swagger2markup.operationDescriptionsEnabled=false
swagger2markup.definitionDescriptionsEnabled=false
swagger2markup.operationExtensionsEnabled=false
swagger2markup.definitionExtensionsEnabled=false
swagger2markup.separatedDefinitionsEnabled=false

21
src/test/java/io/github/swagger2markup/AsciidocConverterTest.java
View File

@@ -210,27 +210,6 @@ public class AsciidocConverterTest {
}
}
@Test
public void testSwagger2AsciiDocConversionWithDefinitionDescriptions() throws IOException, URISyntaxException {
//Given
Path file = Paths.get(AsciidocConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
Path outputDirectory = Paths.get("build/test/asciidoc/generated");
FileUtils.deleteQuietly(outputDirectory.toFile());
//When
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withDefinitionDescriptions(Paths.get("src/test/resources/docs/asciidoc/definitions"))
.build();
Swagger2MarkupConverter.from(file)
.withConfig(config).build()
.toFolder(outputDirectory);
//Then
String[] files = outputDirectory.toFile().list();
assertThat(files).hasSize(4).containsAll(expectedFiles);
}
@Test
public void testSwagger2AsciiDocConversionDoesNotContainUriScheme() throws IOException, URISyntaxException {
//Given

24
src/test/java/io/github/swagger2markup/MarkdownConverterTest.java
View File

@@ -19,9 +19,9 @@ import com.google.common.collect.ImmutableMap;
import com.google.common.collect.ImmutableSet;
import com.google.common.collect.Maps;
import com.google.common.collect.Sets;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import io.github.swagger2markup.assertions.DiffUtils;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.apache.commons.io.FileUtils;
import org.junit.Before;
import org.junit.Test;
@@ -81,28 +81,6 @@ public class MarkdownConverterTest {
DiffUtils.assertThatAllFilesAreEqual(expectedFilesDirectory, outputDirectory, "testSwagger2MarkdownConversion.html");
}
@Test
public void testSwagger2MarkdownConversionWithDescriptions() throws IOException, URISyntaxException {
//Given
Path file = Paths.get(MarkdownConverterTest.class.getResource("/yaml/swagger_petstore.yaml").toURI());
Path outputDirectory = Paths.get("build/test/markdown/generated");
FileUtils.deleteQuietly(outputDirectory.toFile());
//When
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withDefinitionDescriptions(Paths.get("src/test/resources/docs/markdown/definitions"))
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();
Swagger2MarkupConverter.from(file)
.withConfig(config)
.build()
.toFolder(outputDirectory);
//Then
String[] files = outputDirectory.toFile().list();
assertThat(files).hasSize(4).containsAll(expectedFiles);
}
@Test
public void testSwagger2MarkdownConversionWithSeparatedDefinitions() throws IOException, URISyntaxException {
//Given

4
src/test/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilderTest.java
View File

@@ -45,8 +45,6 @@ public class Swagger2MarkupConfigBuilderTest {
assertThat(config.getDefinitionOrderBy()).isEqualTo(OrderBy.NATURAL);
assertThat(config.getDefinitionOrdering()).isEqualTo(Ordering.natural());
assertThat(config.getDefinitionsDocument()).isEqualTo("definitions");
assertThat(config.isOperationDescriptionsEnabled()).isFalse();
assertThat(config.isDefinitionDescriptionsEnabled()).isFalse();
assertThat(config.isGeneratedExamplesEnabled()).isFalse();
assertThat(config.getInlineSchemaDepthLevel()).isEqualTo(0);
assertThat(config.getInterDocumentCrossReferencesPrefix()).isNull();
@@ -91,8 +89,6 @@ public class Swagger2MarkupConfigBuilderTest {
assertThat(config.getDefinitionOrderBy()).isEqualTo(OrderBy.AS_IS);
assertThat(config.getDefinitionOrdering()).isNull();
assertThat(config.getDefinitionsDocument()).isEqualTo("definitionsTest");
assertThat(config.isOperationDescriptionsEnabled()).isFalse();
assertThat(config.isDefinitionDescriptionsEnabled()).isFalse();
assertThat(config.isGeneratedExamplesEnabled()).isTrue();
assertThat(config.getInlineSchemaDepthLevel()).isEqualTo(2);
assertThat(config.getInterDocumentCrossReferencesPrefix()).isEqualTo("xrefPrefix");

5
src/test/resources/docs/asciidoc/definitions/User/description.adoc
View File

@@ -1,5 +0,0 @@
This is a hand-written description.
AsciiDoc is better suited for descriptions than:
* JavaDoc
* Annotations

1
src/test/resources/docs/asciidoc/definitions/User/id/description.adoc
View File

@@ -1 +0,0 @@
This is a hand-written description. AsciiDoc is better suited for descriptions than *JavaDoc* and *Annotations*

1
src/test/resources/docs/asciidoc/definitions/User/username/description.adoc
View File

@@ -1 +0,0 @@
This is a hand-written description. AsciiDoc is better suited for descriptions than *JavaDoc* and *Annotations*

2
src/test/resources/docs/asciidoc/paths/updatePet/body/description.adoc
View File

@@ -1,2 +0,0 @@
This is a hand-written description.
AsciiDoc is better suited for descriptions than *JavaDoc* and *Annotations*

5
src/test/resources/docs/asciidoc/paths/updatePet/description.adoc
View File

@@ -1,5 +0,0 @@
This is a hand-written description.
AsciiDoc is better suited for descriptions than:
* JavaDoc
* Annotations

5
src/test/resources/docs/markdown/definitions/User/description.md
View File

@@ -1,5 +0,0 @@
This is a hand-written description.
AsciiDoc is better suited for descriptions than:
* JavaDoc
* Annotations

1
src/test/resources/docs/markdown/definitions/User/id/description.md
View File

@@ -1 +0,0 @@
This is a hand-written description. AsciiDoc is better suited for descriptions than *JavaDoc* and *Annotations*

1
src/test/resources/docs/markdown/definitions/User/username/description.md
View File

@@ -1 +0,0 @@
This is a hand-written description. AsciiDoc is better suited for descriptions than *JavaDoc* and *Annotations*

1
src/test/resources/docs/markdown/paths/updatePet/body/description.md
View File

@@ -1 +0,0 @@
This is a hand-written description. AsciiDoc is better suited for descriptions than *JavaDoc* and *Annotations*

5
src/test/resources/docs/markdown/paths/updatePet/description.md
View File

@@ -1,5 +0,0 @@
This is a hand-written description.
It is better suited for adding descriptions than:
* JavaDoc
* Annotations