Merge remote-tracking branch 'origin/master'

src/docs/asciidoc/usage_guide.adoc

@@ -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.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.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.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.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.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 path | definitions
+|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 | 
 |===
 

src/main/java/io/github/swagger2markup/Swagger2MarkupConfig.java

@@ -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.
      */

src/main/java/io/github/swagger2markup/Swagger2MarkupProperties.java

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

src/main/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilder.java

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

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

@@ -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));
     }
@@ -233,30 +218,6 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
         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,18 +266,9 @@ public class DefinitionsDocumentBuilder extends MarkupDocumentBuilder {
         return localDefinitions;
     }
     
-    private void buildDescriptionParagraph(String definitionName, Model model, MarkupDocBuilder docBuilder) {
+    private void buildDescriptionParagraph(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 modelDescription(Model model, MarkupDocBuilder docBuilder) {
         String description = model.getDescription();
@@ -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);
             }

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

@@ -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
      */

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

@@ -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,20 +398,8 @@ 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);
-        }
-    }
 
     private void operationDescription(String description, MarkupDocBuilder docBuilder) {
         if (isNotBlank(description)) {
@@ -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);
             }

src/main/resources/io/github/swagger2markup/config/default.properties

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

src/test/java/io/github/swagger2markup/AsciidocConverterTest.java

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

src/test/java/io/github/swagger2markup/MarkdownConverterTest.java

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

src/test/java/io/github/swagger2markup/builder/Swagger2MarkupConfigBuilderTest.java

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

src/test/resources/docs/asciidoc/definitions/User/description.adoc

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

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

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

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

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

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

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

src/test/resources/docs/asciidoc/paths/updatePet/description.adoc

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

src/test/resources/docs/markdown/definitions/User/description.md

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

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

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

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

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

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

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

src/test/resources/docs/markdown/paths/updatePet/description.md

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