Merge remote-tracking branch 'upstream/master' into separatedBody

2016-02-05 18:02:37 +01:00
parent 2fceda6f09 2aa29fde8a
commit 4e340466de
7 changed files with 177 additions and 101 deletions
--- a/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java
+++ b/src/main/java/io/github/robwin/swagger2markup/Swagger2MarkupConverter.java
@@ -159,7 +159,7 @@ public class Swagger2MarkupConverter {
     */
    private void buildDocuments(String directory) throws IOException {
        new OverviewDocument(swagger2MarkupConfig).build().writeToFile(directory, OVERVIEW_DOCUMENT, StandardCharsets.UTF_8);
-        new PathsDocument(swagger2MarkupConfig).build().writeToFile(directory, PATHS_DOCUMENT, StandardCharsets.UTF_8);
+        new PathsDocument(swagger2MarkupConfig, directory).build().writeToFile(directory, PATHS_DOCUMENT, StandardCharsets.UTF_8);
        new DefinitionsDocument(swagger2MarkupConfig, directory).build().writeToFile(directory, DEFINITIONS_DOCUMENT, StandardCharsets.UTF_8);
    }

@@ -170,7 +170,7 @@ public class Swagger2MarkupConverter {
     */
    private String buildDocuments() {
        return new OverviewDocument(swagger2MarkupConfig).build().toString()
-                .concat(new PathsDocument(swagger2MarkupConfig).build().toString()
+                .concat(new PathsDocument(swagger2MarkupConfig, null).build().toString()
                .concat(new DefinitionsDocument(swagger2MarkupConfig, null).build().toString()));
    }

@@ -181,6 +181,7 @@ public class Swagger2MarkupConverter {
        private String schemasFolderPath;
        private String descriptionsFolderPath;
        private boolean separatedDefinitions;
+        private boolean separatedPaths;
        private GroupBy pathsGroupedBy = GroupBy.AS_IS;
        private OrderBy definitionsOrderedBy = OrderBy.NATURAL;
        private MarkupLanguage markupLanguage = MarkupLanguage.ASCIIDOC;
@@ -213,7 +214,7 @@ public class Swagger2MarkupConverter {

        public Swagger2MarkupConverter build(){
            return new Swagger2MarkupConverter(new Swagger2MarkupConfig(swagger, markupLanguage, examplesFolderPath,
-                    schemasFolderPath, descriptionsFolderPath, separatedDefinitions, pathsGroupedBy, definitionsOrderedBy,
+                    schemasFolderPath, descriptionsFolderPath, separatedDefinitions, separatedPaths, pathsGroupedBy, definitionsOrderedBy,
                    outputLanguage, inlineSchemaDepthLevel, tagComparator, pathComparator, pathMethodComparator));
        }

@@ -248,6 +249,15 @@ public class Swagger2MarkupConverter {
            return this;
        }

+        /**
+         * In addition to the paths file, also create separate path files for each path.
+         * @return the Swagger2MarkupConverter.Builder
+         */
+        public Builder withSeparatedPaths() {
+            this.separatedPaths = true;
+            return this;
+        }
+
        /**
         * Include examples into the Paths document
         *
--- a/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java
+++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/DefinitionsDocument.java
@@ -58,6 +58,7 @@ public class DefinitionsDocument extends MarkupDocument {
    private static final String XML = "xml";
    private static final String DESCRIPTION_FOLDER_NAME = "definitions";
    private static final String DESCRIPTION_FILE_NAME = "description";
+    private static final String SEPARATED_DEFINITIONS_FOLDER_NAME = "definitions";
    private boolean schemasEnabled;
    private String schemasFolderPath;
    private boolean handWrittenDescriptionsEnabled;
@@ -120,7 +121,7 @@ public class DefinitionsDocument extends MarkupDocument {

    @Override
    public MarkupDocument build(){
-        definitions(swagger.getDefinitions(), this.markupDocBuilder);
+        definitions(swagger.getDefinitions());
        return this;
    }

@@ -128,11 +129,10 @@ public class DefinitionsDocument extends MarkupDocument {
     * Builds the Swagger definitions.
     *
     * @param definitions the Swagger definitions
-     * @param docBuilder the doc builder to use for output
     */
-    private void definitions(Map<String, Model> definitions, MarkupDocBuilder docBuilder){
+    private void definitions(Map<String, Model> definitions){
        if(MapUtils.isNotEmpty(definitions)){
-            docBuilder.sectionTitleLevel1(DEFINITIONS);
+            this.markupDocBuilder.sectionTitleLevel1(DEFINITIONS);
            Set<String> definitionNames;
            if(definitionsOrderedBy.equals(OrderBy.AS_IS)){
                definitionNames = definitions.keySet();
@@ -143,23 +143,7 @@ public class DefinitionsDocument extends MarkupDocument {
                Model model = definitions.get(definitionName);
                if(isNotBlank(definitionName)) {
                    if (checkThatDefinitionIsNotInIgnoreList(definitionName)) {
-                        definition(definitions, definitionName, model, docBuilder);
-                        definitionSchema(definitionName, docBuilder);
-                        if (separatedDefinitionsEnabled) {
-                            MarkupDocBuilder defDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage);
-                            definition(definitions, definitionName, model, defDocBuilder);
-                            definitionSchema(definitionName, defDocBuilder);
-                            try {
-                                defDocBuilder.writeToFile(outputDirectory, definitionName.toLowerCase(), StandardCharsets.UTF_8);
-                            } catch (IOException e) {
-                                if (logger.isWarnEnabled()) {
-                                    logger.warn(String.format("Failed to write definition file: %s", definitionName), e);
-                                }
-                            }
-                            if (logger.isInfoEnabled()) {
-                                logger.info("Separate definition file produced: {}", definitionName);
-                            }
-                        }
+                        processDefinition(definitions, definitionName, model);
                        if (logger.isInfoEnabled()) {
                            logger.info("Definition processed: {}", definitionName);
                        }
@@ -173,6 +157,27 @@ public class DefinitionsDocument extends MarkupDocument {
        }
    }

+    private void processDefinition(Map<String, Model> definitions, String definitionName, Model model) {
+
+        definition(definitions, definitionName, model, this.markupDocBuilder);
+
+        if (separatedDefinitionsEnabled) {
+            MarkupDocBuilder defDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage);
+            definition(definitions, definitionName, model, defDocBuilder);
+            String definitionFileName = definitionName.toLowerCase();
+            try {
+                defDocBuilder.writeToFile(Paths.get(outputDirectory, SEPARATED_DEFINITIONS_FOLDER_NAME).toString(), definitionFileName, StandardCharsets.UTF_8);
+            } catch (IOException e) {
+                if (logger.isWarnEnabled()) {
+                    logger.warn(String.format("Failed to write definition file: %s", definitionFileName), e);
+                }
+            }
+            if (logger.isInfoEnabled()) {
+                logger.info("Separate definition file produced: {}", definitionFileName);
+            }
+        }
+    }
+
    /**
     * Checks that the definition is not in the list of ignored definitions.
     *
@@ -194,6 +199,7 @@ public class DefinitionsDocument extends MarkupDocument {
        docBuilder.sectionTitleLevel2(definitionName);
        descriptionSection(definitionName, model, docBuilder);
        propertiesSection(definitions, definitionName, model, docBuilder);
+        definitionSchema(definitionName, docBuilder);
    }

    private class DefinitionPropertyDescriptor extends PropertyDescriptor {
@@ -352,7 +358,7 @@ public class DefinitionsDocument extends MarkupDocument {
     * Inline definitions should never been referenced in TOC, so they are just text.
     */
    private void addInlineDefinitionTitle(String title, String anchor, MarkupDocBuilder docBuilder) {
-        docBuilder.anchor(anchor);
+        docBuilder.anchor(anchor, null);
        docBuilder.newLine();
        docBuilder.boldTextLine(title);
    }
--- a/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java
+++ b/src/main/java/io/github/robwin/swagger2markup/builder/document/PathsDocument.java
@@ -20,6 +20,8 @@ package io.github.robwin.swagger2markup.builder.document;

 import com.google.common.base.Optional;
 import com.google.common.collect.Multimap;
+import io.github.robwin.markup.builder.MarkupDocBuilder;
+import io.github.robwin.markup.builder.MarkupDocBuilders;
 import io.github.robwin.markup.builder.MarkupTableColumn;
 import io.github.robwin.swagger2markup.GroupBy;
 import io.github.robwin.swagger2markup.config.Swagger2MarkupConfig;
@@ -35,6 +37,7 @@ import io.swagger.models.properties.Property;
 import org.apache.commons.collections.CollectionUtils;
 import org.apache.commons.collections.MapUtils;
 import org.apache.commons.io.FileUtils;
+import org.apache.commons.lang3.Validate;
 import org.apache.commons.lang3.text.WordUtils;
 import org.apache.commons.lang3.tuple.Pair;

@@ -43,6 +46,7 @@ import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.util.*;
+import java.util.regex.Pattern;

 import static io.github.robwin.swagger2markup.utils.TagUtils.*;
 import static org.apache.commons.lang3.StringUtils.defaultString;
@@ -53,7 +57,7 @@ import static org.apache.commons.lang3.StringUtils.isNotBlank;
 */
 public class PathsDocument extends MarkupDocument {

-    private static final String RESPONSE_INLINE_PREFIX = "Response";
+    private final String RESPONSE;
    private final String PATHS;
    private final String RESOURCES;
    private final String PARAMETERS;
@@ -68,8 +72,9 @@ public class PathsDocument extends MarkupDocument {
    private static final String CURL_EXAMPLE_FILE_NAME = "curl-request";
    private static final String DESCRIPTION_FOLDER_NAME = "paths";
    private static final String DESCRIPTION_FILE_NAME = "description";
+    private static final String SEPARATED_PATHS_FOLDER_NAME = "paths";
    private final String PARAMETER;
-
+    private static final Pattern FILENAME_FORBIDDEN_PATTERN = Pattern.compile("[^0-9A-Za-z-_]+");

    private boolean examplesEnabled;
    private String examplesFolderPath;
@@ -80,12 +85,15 @@ public class PathsDocument extends MarkupDocument {
    private final Comparator<String> tagComparator;
    private final Comparator<String> pathComparator;
    private final Comparator<HttpMethod> pathMethodComparator;
+    private boolean separatedPathsEnabled;
+    private String outputDirectory;

-    public PathsDocument(Swagger2MarkupConfig swagger2MarkupConfig){
+    public PathsDocument(Swagger2MarkupConfig swagger2MarkupConfig, String outputDirectory){
        super(swagger2MarkupConfig);

        ResourceBundle labels = ResourceBundle.getBundle("lang/labels",
                swagger2MarkupConfig.getOutputLanguage().toLocale());
+        RESPONSE = labels.getString("response");
        PATHS = labels.getString("paths");
        RESOURCES = labels.getString("resources");
        PARAMETERS = labels.getString("parameters");
@@ -107,6 +115,7 @@ public class PathsDocument extends MarkupDocument {
            this.handWrittenDescriptionsEnabled = true;
            this.descriptionsFolderPath = swagger2MarkupConfig.getDescriptionsFolderPath() + "/" + DESCRIPTION_FOLDER_NAME;
        }
+
        if(examplesEnabled){
            if (logger.isDebugEnabled()) {
                logger.debug("Include examples is enabled.");
@@ -125,6 +134,19 @@ public class PathsDocument extends MarkupDocument {
                logger.debug("Include hand-written descriptions is disabled.");
            }
        }
+
+        this.separatedPathsEnabled = swagger2MarkupConfig.isSeparatedPaths();
+        if(this.separatedPathsEnabled){
+            if (logger.isDebugEnabled()) {
+                logger.debug("Create separated path files is enabled.");
+            }
+            Validate.notEmpty(outputDirectory, "Output directory is required for separated path files!");
+        }else{
+            if (logger.isDebugEnabled()) {
+                logger.debug("Create separated path files is disabled.");
+            }
+        }
+        this.outputDirectory = outputDirectory;
        tagComparator = swagger2MarkupConfig.getTagComparator();
        pathComparator = swagger2MarkupConfig.getPathComparator();
        pathMethodComparator = swagger2MarkupConfig.getPathMethodComparator();
@@ -192,26 +214,50 @@ public class PathsDocument extends MarkupDocument {

        for(Map.Entry<HttpMethod, Operation> operationEntry : operationsMap.entrySet()){
            String methodAndPath = operationEntry.getKey() + " " + pathUrl;
-            path(methodAndPath, operationEntry.getValue());
+            processPath(methodAndPath, operationEntry.getValue());
+        }
+    }
+
+     private void processPath(String methodAndPath, Operation operation) {
+
+         path(methodAndPath, operation, this.markupDocBuilder);
+
+        if (separatedPathsEnabled) {
+            MarkupDocBuilder pathDocBuilder = MarkupDocBuilders.documentBuilder(markupLanguage);
+            path(methodAndPath, operation, pathDocBuilder);
+            String pathFileName = operation.getOperationId();
+            if (pathFileName == null)
+                pathFileName = methodAndPath;
+            pathFileName = FILENAME_FORBIDDEN_PATTERN.matcher(pathFileName).replaceAll("_").toLowerCase();
+            try {
+                pathDocBuilder.writeToFile(Paths.get(outputDirectory, SEPARATED_PATHS_FOLDER_NAME).toString(), pathFileName, StandardCharsets.UTF_8);
+            } catch (IOException e) {
+                if (logger.isWarnEnabled()) {
+                    logger.warn(String.format("Failed to write path file: %s", pathFileName), e);
+                }
+            }
+            if (logger.isInfoEnabled()) {
+                logger.info("Separate path file produced: {}", pathFileName);
+            }
        }
    }

    /**
-     * Builds a path.
+     * Builds an operation.
     *
     * @param methodAndPath the Method of the operation and the URL of the path
     * @param operation the Swagger Operation
     */
-    private void path(String methodAndPath, Operation operation) {
+    private void path(String methodAndPath, Operation operation, MarkupDocBuilder docBuilder) {
        if(operation != null){
-            pathTitle(methodAndPath, operation);
-            descriptionSection(operation);
-            inlineDefinitions(parametersSection(operation), inlineSchemaDepthLevel);
-            inlineDefinitions(responsesSection(operation), inlineSchemaDepthLevel);
-            consumesSection(operation);
-            producesSection(operation);
-            tagsSection(operation);
-            examplesSection(operation);
+            pathTitle(methodAndPath, operation, docBuilder);
+            descriptionSection(operation, docBuilder);
+            inlineDefinitions(parametersSection(operation, docBuilder), inlineSchemaDepthLevel, docBuilder);
+            inlineDefinitions(responsesSection(operation, docBuilder), inlineSchemaDepthLevel, docBuilder);
+            consumesSection(operation, docBuilder);
+            producesSection(operation, docBuilder);
+            tagsSection(operation, docBuilder);
+            examplesSection(operation, docBuilder);
        }
    }

@@ -222,15 +268,15 @@ public class PathsDocument extends MarkupDocument {
     * @param methodAndPath the Method of the operation and the URL of the path
     * @param operation the Swagger Operation
     */
-    private void pathTitle(String methodAndPath, Operation operation) {
+    private void pathTitle(String methodAndPath, Operation operation, MarkupDocBuilder docBuilder) {
        String summary = operation.getSummary();
        String title;
        if(isNotBlank(summary)) {
            title = summary;
-            addPathTitle(title);
-            this.markupDocBuilder.listing(methodAndPath);
+            addPathTitle(title, docBuilder);
+            docBuilder.listing(methodAndPath);
        }else{
-            addPathTitle(methodAndPath);
+            addPathTitle(methodAndPath, docBuilder);
        }
        if (logger.isInfoEnabled()) {
            logger.info("Path processed: {}", methodAndPath);
@@ -242,11 +288,11 @@ public class PathsDocument extends MarkupDocument {
     *
     * @param title the path title
     */
-    private void addPathTitle(String title) {
+    private void addPathTitle(String title, MarkupDocBuilder docBuilder) {
        if(pathsGroupedBy == GroupBy.AS_IS || pathsGroupedBy == GroupBy.SORTED){
-            this.markupDocBuilder.sectionTitleLevel2(title);
+            docBuilder.sectionTitleLevel2(title);
        }else{
-            this.markupDocBuilder.sectionTitleLevel3(title);
+            docBuilder.sectionTitleLevel3(title);
        }
    }

@@ -255,11 +301,11 @@ public class PathsDocument extends MarkupDocument {
     *
     * @param title the path title
     */
-    private void addPathSectionTitle(String title) {
+    private void addPathSectionTitle(String title, MarkupDocBuilder docBuilder) {
        if(pathsGroupedBy == GroupBy.AS_IS || pathsGroupedBy == GroupBy.SORTED){
-            this.markupDocBuilder.sectionTitleLevel3(title);
+            docBuilder.sectionTitleLevel3(title);
        }else{
-            this.markupDocBuilder.sectionTitleLevel4(title);
+            docBuilder.sectionTitleLevel4(title);
        }
    }

@@ -268,39 +314,39 @@ public class PathsDocument extends MarkupDocument {
     *
     * @param operation the Swagger Operation
     */
-    private void descriptionSection(Operation operation) {
+    private void descriptionSection(Operation operation, MarkupDocBuilder docBuilder) {
        if(handWrittenDescriptionsEnabled){
            String summary = operation.getSummary();
            if(isNotBlank(summary)) {
                String operationFolder = summary.replace(".", "").replace(" ", "_").toLowerCase();
                Optional<String> description = handWrittenPathDescription(operationFolder, DESCRIPTION_FILE_NAME);
                if(description.isPresent()){
-                    pathDescription(description.get());
+                    pathDescription(description.get(), docBuilder);
                }else{
                    if (logger.isInfoEnabled()) {
                        logger.info("Hand-written description cannot be read. Trying to use description from Swagger source.");
                    }
-                    pathDescription(operation.getDescription());
+                    pathDescription(operation.getDescription(), docBuilder);
                }
            }else{
                if (logger.isInfoEnabled()) {
                    logger.info("Hand-written description cannot be read, because summary of operation is empty. Trying to use description from Swagger source.");
                }
-                pathDescription(operation.getDescription());
+                pathDescription(operation.getDescription(), docBuilder);
            }
        }else {
-            pathDescription(operation.getDescription());
+            pathDescription(operation.getDescription(), docBuilder);
        }
    }

-    private void pathDescription(String description) {
+    private void pathDescription(String description, MarkupDocBuilder docBuilder) {
        if (isNotBlank(description)) {
-            addPathSectionTitle(DESCRIPTION);
-            this.markupDocBuilder.paragraph(description);
+            addPathSectionTitle(DESCRIPTION, docBuilder);
+            docBuilder.paragraph(description);
        }
    }

-    private List<Type> parametersSection(Operation operation) {
+    private List<Type> parametersSection(Operation operation, MarkupDocBuilder docBuilder) {
        List<Parameter> parameters = operation.getParameters();
        List<Type> localDefinitions = new ArrayList<>();
        if(CollectionUtils.isNotEmpty(parameters)){
@@ -329,14 +375,14 @@ public class PathsDocument extends MarkupDocument {
                List<String> content = Arrays.asList(
                        parameterType,
                        parameter.getName(),
-                        parameterDescription(operation, parameter),
+                        parameterDescription(operation, parameter, docBuilder),
                        Boolean.toString(parameter.getRequired()),
                        type.displaySchema(markupDocBuilder),
                        ParameterUtils.getDefaultValue(parameter));
               cells.add(content);
            }
-            addPathSectionTitle(PARAMETERS);
-            markupDocBuilder.tableWithColumnSpecs(cols, cells);
+            addPathSectionTitle(PARAMETERS, docBuilder);
+            docBuilder.tableWithColumnSpecs(cols, cells);
        }

        return localDefinitions;
@@ -351,7 +397,7 @@ public class PathsDocument extends MarkupDocument {
     * @param parameter the Swagger Parameter
     * @return the description of a parameter.
     */
-    private String parameterDescription(Operation operation, Parameter parameter){
+    private String parameterDescription(Operation operation, Parameter parameter, MarkupDocBuilder docBuilder){
        if(handWrittenDescriptionsEnabled){
            String summary = operation.getSummary();
            String operationFolder = summary.replace(".", "").replace(" ", "_").toLowerCase();
@@ -378,28 +424,28 @@ public class PathsDocument extends MarkupDocument {
        }
    }

-    private void consumesSection(Operation operation) {
+    private void consumesSection(Operation operation, MarkupDocBuilder docBuilder) {
        List<String> consumes = operation.getConsumes();
        if(CollectionUtils.isNotEmpty(consumes)){
-            addPathSectionTitle(CONSUMES);
-            this.markupDocBuilder.unorderedList(consumes);
+            addPathSectionTitle(CONSUMES, docBuilder);
+            docBuilder.unorderedList(consumes);
        }

    }

-    private void producesSection(Operation operation) {
+    private void producesSection(Operation operation, MarkupDocBuilder docBuilder) {
        List<String> produces = operation.getProduces();
        if(CollectionUtils.isNotEmpty(produces)){
-            addPathSectionTitle(PRODUCES);
-            this.markupDocBuilder.unorderedList(produces);
+            addPathSectionTitle(PRODUCES, docBuilder);
+            docBuilder.unorderedList(produces);
        }
    }

-    private void tagsSection(Operation operation) {
+    private void tagsSection(Operation operation, MarkupDocBuilder docBuilder) {
        if(pathsGroupedBy == GroupBy.AS_IS || pathsGroupedBy == GroupBy.SORTED) {
            List<String> tags = operation.getTags();
            if (CollectionUtils.isNotEmpty(tags)) {
-                addPathSectionTitle(TAGS);
+                addPathSectionTitle(TAGS, docBuilder);
                Set<String> orderedTags = new TreeSet<>(this.tagComparator);
                orderedTags.addAll(tags);
                this.markupDocBuilder.unorderedList(new ArrayList<>(orderedTags));
@@ -414,26 +460,26 @@ public class PathsDocument extends MarkupDocument {
     *
     * @param operation the Swagger Operation
     */
-    private void examplesSection(Operation operation) {
+    private void examplesSection(Operation operation, MarkupDocBuilder docBuilder) {
        if(examplesEnabled){
            String summary = operation.getSummary();
            if(isNotBlank(summary)) {
                String exampleFolder = summary.replace(".", "").replace(" ", "_").toLowerCase();
                Optional<String> curlExample = example(exampleFolder, CURL_EXAMPLE_FILE_NAME);
                if(curlExample.isPresent()){
-                    addPathSectionTitle(EXAMPLE_CURL);
-                    this.markupDocBuilder.paragraph(curlExample.get());
+                    addPathSectionTitle(EXAMPLE_CURL, docBuilder);
+                    docBuilder.paragraph(curlExample.get());
                }

                Optional<String> requestExample = example(exampleFolder, REQUEST_EXAMPLE_FILE_NAME);
                if(requestExample.isPresent()){
-                    addPathSectionTitle(EXAMPLE_REQUEST);
-                    this.markupDocBuilder.paragraph(requestExample.get());
+                    addPathSectionTitle(EXAMPLE_REQUEST, docBuilder);
+                    docBuilder.paragraph(requestExample.get());
                }
                Optional<String> responseExample = example(exampleFolder, RESPONSE_EXAMPLE_FILE_NAME);
                if(responseExample.isPresent()){
-                    addPathSectionTitle(EXAMPLE_RESPONSE);
-                    this.markupDocBuilder.paragraph(responseExample.get());
+                    addPathSectionTitle(EXAMPLE_RESPONSE, docBuilder);
+                    docBuilder.paragraph(responseExample.get());
                }
            }else{
                if (logger.isWarnEnabled()) {
@@ -509,7 +555,7 @@ public class PathsDocument extends MarkupDocument {
        return Optional.absent();
    }

-    private List<Type> responsesSection(Operation operation) {
+    private List<Type> responsesSection(Operation operation, MarkupDocBuilder docBuilder) {
        Map<String, Response> responses = operation.getResponses();
        List<Type> localDefinitions = new ArrayList<>();
        if(MapUtils.isNotEmpty(responses)){
@@ -525,7 +571,7 @@ public class PathsDocument extends MarkupDocument {
                    Type type = PropertyUtils.getType(property);
                    if (this.inlineSchemaDepthLevel > 0 && type instanceof ObjectType) {
                        if (MapUtils.isNotEmpty(((ObjectType) type).getProperties())) {
-                            String localTypeName = RESPONSE_INLINE_PREFIX + " " + entry.getKey();
+                            String localTypeName = RESPONSE + " " + entry.getKey();

                            type.setName(localTypeName);
                            type.setUniqueName(uniqueTypeName(localTypeName));
@@ -538,8 +584,8 @@ public class PathsDocument extends MarkupDocument {
                    cells.add(Arrays.asList(entry.getKey(), response.getDescription(), NO_CONTENT));
                }
            }
-            addPathSectionTitle(RESPONSES);
-            markupDocBuilder.tableWithColumnSpecs(cols, cells);
+            addPathSectionTitle(RESPONSES, docBuilder);
+            docBuilder.tableWithColumnSpecs(cols, cells);
        }
        return localDefinitions;
    }
@@ -547,19 +593,19 @@ public class PathsDocument extends MarkupDocument {
    /**
     * Inline definitions should never been referenced in TOC, so they are just text.
     */
-    private void addInlineDefinitionTitle(String title, String anchor) {
-        markupDocBuilder.anchor(anchor);
-        markupDocBuilder.newLine();
-        this.markupDocBuilder.boldTextLine(title);
+    private void addInlineDefinitionTitle(String title, String anchor, MarkupDocBuilder docBuilder) {
+        docBuilder.anchor(anchor, null);
+        docBuilder.newLine();
+        docBuilder.boldTextLine(title);
    }

-    private void inlineDefinitions(List<Type> definitions, int depth) {
+    private void inlineDefinitions(List<Type> definitions, int depth, MarkupDocBuilder docBuilder) {
        if(CollectionUtils.isNotEmpty(definitions)){
            for (Type definition: definitions) {
-                addInlineDefinitionTitle(definition.getName(), definition.getUniqueName());
+                addInlineDefinitionTitle(definition.getName(), definition.getUniqueName(), docBuilder);
                List<Type> localDefinitions = typeProperties(definition, depth, new PropertyDescriptor(definition), this.markupDocBuilder);
                for (Type localDefinition : localDefinitions)
-                    inlineDefinitions(Collections.singletonList(localDefinition), depth - 1);
+                    inlineDefinitions(Collections.singletonList(localDefinition), depth - 1, docBuilder);
            }
        }

--- a/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java
+++ b/src/main/java/io/github/robwin/swagger2markup/config/Swagger2MarkupConfig.java
@@ -35,6 +35,7 @@ public class Swagger2MarkupConfig {
    private final String schemasFolderPath;
    private final String descriptionsFolderPath;
    private final boolean separatedDefinitions;
+    private final boolean separatedPaths;
    private final GroupBy pathsGroupedBy;
    private final OrderBy definitionsOrderedBy;
    private final Language outputLanguage;
@@ -50,6 +51,7 @@ public class Swagger2MarkupConfig {
     * @param schemasFolderPath the path to the folder where the schema documents reside
     * @param descriptionsFolderPath the path to the folder where the description documents reside
     * @param separatedDefinitions specified if in addition to the definitions file, also separate definition files for each model definition should be created
+     * @param separatedPaths specified if in addition to the paths file, also separate path files for each path should be created
     * @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
@@ -59,7 +61,7 @@ public class Swagger2MarkupConfig {
     * @param pathMethodComparator specifies a custom comparator function to order paths methods
     */
    public Swagger2MarkupConfig(Swagger swagger, MarkupLanguage markupLanguage, String examplesFolderPath,
-                                String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions,
+                                String schemasFolderPath, String descriptionsFolderPath, boolean separatedDefinitions, boolean separatedPaths,
                                GroupBy pathsGroupedBy, OrderBy definitionsOrderedBy, Language outputLanguage,
                                int inlineSchemaDepthLevel, Comparator<String> tagComparator, Comparator<String> pathComparator,
                                Comparator<HttpMethod> pathMethodComparator) {
@@ -69,6 +71,7 @@ public class Swagger2MarkupConfig {
        this.schemasFolderPath = schemasFolderPath;
        this.descriptionsFolderPath = descriptionsFolderPath;
        this.separatedDefinitions = separatedDefinitions;
+        this.separatedPaths = separatedPaths;
        this.pathsGroupedBy = pathsGroupedBy;
        this.definitionsOrderedBy = definitionsOrderedBy;
        this.outputLanguage = outputLanguage;
@@ -102,6 +105,10 @@ public class Swagger2MarkupConfig {
        return separatedDefinitions;
    }

+    public boolean isSeparatedPaths() {
+        return separatedPaths;
+    }
+
    public GroupBy getPathsGroupedBy() {
        return pathsGroupedBy;
    }
--- a/src/main/resources/lang/labels_en.properties
+++ b/src/main/resources/lang/labels_en.properties
@@ -30,6 +30,7 @@ paths=Paths
 resources=Resources
 parameters=Parameters
 responses=Responses
+response=Response
 example_curl=Example CURL request
 example_request=Example HTTP request
 example_response=Example HTTP response
--- a/src/main/resources/lang/labels_ru.properties
+++ b/src/main/resources/lang/labels_ru.properties
@@ -28,6 +28,7 @@ schemes=\u0421\u0445\u0435\u043C\u044B\:\u0020

 paths=\u041F\u0443\u0442\u0438
 resources=\u041E\u0442\u0432\u0435\u0442\u044B
+response=Response
 parameters=\u041F\u0430\u0440\u0430\u043C\u0435\u0442\u0440\u044B
 responses=\u041E\u0442\u0432\u0435\u0442\u044B
 example_curl=\u041F\u0440\u0438\u043C\u0435\u0440 CURL \u0437\u0430\u043F\u0440\u043E\u0441\u0430
--- a/src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java
+++ b/src/test/java/io/github/robwin/swagger2markup/Swagger2MarkupConverterTest.java
@@ -247,11 +247,11 @@ public class Swagger2MarkupConverterTest {

        //Then
        String[] directories = outputDirectory.list();
-        assertThat(directories).hasSize(9).containsAll(
-            asList("definitions.adoc", "overview.adoc", "paths.adoc", "identified.adoc",
-                "user.adoc", "category.adoc", "pet.adoc", "tag.adoc", "order.adoc"));
+        assertThat(directories).hasSize(4).containsAll(
+            asList("definitions", "definitions.adoc", "overview.adoc", "paths.adoc"));
+        File definitionsDirectory = new File(outputDirectory, "definitions");
        assertThat(new String(Files.readAllBytes(new File(outputDirectory, "definitions.adoc").toPath())))
-            .contains(new String(Files.readAllBytes(new File(outputDirectory, "user.adoc").toPath())));
+            .contains(new String(Files.readAllBytes(new File(definitionsDirectory, "user.adoc").toPath())));
    }

    @Test
@@ -268,11 +268,16 @@ public class Swagger2MarkupConverterTest {

        //Then
        String[] directories = outputDirectory.list();
-        assertThat(directories).hasSize(9).containsAll(
-                asList("definitions.md", "overview.md", "paths.md", "identified.md",
-                        "user.md", "category.md", "pet.md", "tag.md", "order.md"));
+        assertThat(directories).hasSize(4).containsAll(
+                asList("definitions", "definitions.md", "overview.md", "paths.md"));
+
+        File definitionsDirectory = new File(outputDirectory, "definitions");
+        String[] definitions = definitionsDirectory.list();
+        assertThat(definitions).hasSize(6).containsAll(
+                asList("identified.md", "user.md", "category.md", "pet.md", "tag.md", "order.md"));
+
        assertThat(new String(Files.readAllBytes(new File(outputDirectory, "definitions.md").toPath())))
-                .contains(new String(Files.readAllBytes(new File(outputDirectory, "user.md").toPath())));
+                .contains(new String(Files.readAllBytes(new File(definitionsDirectory, "user.md").toPath())));
    }

    @Test
@@ -289,9 +294,8 @@ public class Swagger2MarkupConverterTest {

        // Then
        String[] directories = outputDirectory.list();
-        assertThat(directories).hasSize(9).containsAll(
-                asList("definitions.md", "overview.md", "paths.md", "identified.md",
-                        "user.md", "category.md", "pet.md", "tag.md", "order.md"));
+        assertThat(directories).hasSize(4).containsAll(
+                asList("definitions", "definitions.md", "overview.md", "paths.md"));
        verifyMarkdownContainsFieldsInTables(
                new File(outputDirectory, "definitions.md"),
                ImmutableMap.<String, Set<String>>builder()
@@ -299,8 +303,9 @@ public class Swagger2MarkupConverterTest {
                        .put("User", ImmutableSet.of("id", "username", "firstName",
                                "lastName", "email", "password", "phone", "userStatus"))
                        .build());
+        File definitionsDirectory = new File(outputDirectory, "definitions");
        verifyMarkdownContainsFieldsInTables(
-                new File(outputDirectory, "user.md"),
+                new File(definitionsDirectory, "user.md"),
                ImmutableMap.<String, Set<String>>builder()
                        .put("User", ImmutableSet.of("id", "username", "firstName",
                                "lastName", "email", "password", "phone", "userStatus"))