diff --git a/build.gradle b/build.gradle index 4689ee51..011317b0 100644 --- a/build.gradle +++ b/build.gradle @@ -40,7 +40,7 @@ repositories { dependencies { compile 'io.github.swagger2markup:markup-document-builder:1.0.0-SNAPSHOT' - compile 'io.swagger:swagger-compat-spec-parser:1.0.17' + compile 'io.swagger:swagger-compat-spec-parser:1.0.18' compile 'org.apache.commons:commons-configuration2:2.0' compile 'commons-beanutils:commons-beanutils:1.9.2' compile 'org.apache.commons:commons-collections4:4.1' diff --git a/src/docs/asciidoc/extension_spi.adoc b/src/docs/asciidoc/extension_spi.adoc index 1e7aa869..3184357b 100644 --- a/src/docs/asciidoc/extension_spi.adoc +++ b/src/docs/asciidoc/extension_spi.adoc @@ -15,7 +15,10 @@ Swagger2Markup provides an Extension SPI to extend the functionality of Swagger2 === Creation of an extension -To create a custom extension, you have to create a class (e.g. `io.myname.MyExtension`) which extends an extension point, e.g. `io.github.swagger2markup.spi.DefinitionsDocumentExtension`. +To create a custom extension, you have to create a class (e.g. `io.myname.MyExtension`) which extends an extension point, e.g. `io.github.swagger2markup.spi.DefinitionsDocumentExtension`. Every extension point provides to methods which must be implemented: + +* `init`: This method is invoked once +* `apply`: This method is invoked multiple times depending on the type of the extension point. [source,java,indent=0] ---- @@ -47,7 +50,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=sw 3. Build an instance of `Swagger2MarkupExtensionRegistry` 4. Use the custom Swagger2MarkupExtensionRegistry -=== Available extensions points +=== Extensions points ==== OverviewDocumentExtension @@ -62,8 +65,44 @@ image::images/overview_extension_points.PNG[] ==== PathsDocumentExtension +The PathsDocumentExtension allows to extend the paths document at five positions: + +* DOCUMENT_BEFORE: Before the section title +* DOCUMENT_START: After the section title and before the description +* DOCUMENT_BEFORE: At the end of the document +* OPERATION_BEGIN: At the beginning of a path operation section +* OPERATION_END: At the end of a path operation section + ==== SecurityDocumentExtension +The SecurityDocumentExtension allows to extend the security document at five positions: + +* DOCUMENT_BEFORE: Before the section title +* DOCUMENT_START: After the section title and before the description +* DOCUMENT_BEFORE: At the end of the document +* DEFINITION_BEGIN: At the beginning of a security scheme definition section +* DEFINITION_END: At the end of a security scheme definition section + ==== DefinitionsDocumentExtension -==== SwaggerModelExtension \ No newline at end of file +The DefinitionsDocumentExtension allows to extend the definitions document at five positions: + +* DOCUMENT_BEFORE: Before the section title +* DOCUMENT_START: After the section title and before the description +* DOCUMENT_BEFORE: At the end of the document +* DEFINITION_BEGIN: At the beginning of a model definition sectiin +* DEFINITION_END: At the end of a model definition section + + +==== SwaggerModelExtension + +The SwaggerModelExtension allows to modify the Swagger model before it is processed by Swagger2Markup. + +=== Provided Extensions + +Swagger2Markup provides some extensions which can be used out-of-the-box. + +1. An extension which allows to dynamically import Markup from files. +2. An extension which allows to import example Curl, HTTP request and response snippets from Spring Rest Docs. +3. An extension which allows to import JSON or XML Schema files. + diff --git a/src/main/java/io/github/swagger2markup/internal/utils/ExamplesUtil.java b/src/main/java/io/github/swagger2markup/internal/utils/ExamplesUtil.java index ee7e2792..44bfe2db 100644 --- a/src/main/java/io/github/swagger2markup/internal/utils/ExamplesUtil.java +++ b/src/main/java/io/github/swagger2markup/internal/utils/ExamplesUtil.java @@ -120,7 +120,7 @@ public class ExamplesUtil { if (abstractSerializableParameterExample == null) { Property item = ((AbstractSerializableParameter) parameter).getItems(); if (item != null) { - abstractSerializableParameterExample = PropertyUtils.convertExample(item.getExample(), item.getType()); + abstractSerializableParameterExample = item.getExample(); if (abstractSerializableParameterExample == null) { abstractSerializableParameterExample = PropertyUtils.generateExample(item, markupDocBuilder); } @@ -222,7 +222,7 @@ public class ExamplesUtil { public static Map exampleMapForProperties(Map properties, Map definitions, MarkupDocBuilder markupDocBuilder) { Map exampleMap = new LinkedHashMap<>(); for (Map.Entry property : properties.entrySet()) { - Object exampleObject = PropertyUtils.convertExample(property.getValue().getExample(), property.getValue().getType()); + Object exampleObject = property.getValue().getExample(); if (exampleObject == null) { if (property.getValue() instanceof RefProperty) { exampleObject = generateExampleForRefModel(true, ((RefProperty) property.getValue()).getSimpleRef(), definitions, markupDocBuilder); @@ -262,7 +262,7 @@ public class ExamplesUtil { } else { Property itemProperty = model.getItems(); if (itemProperty.getExample() != null) { - return new Object[]{PropertyUtils.convertExample(itemProperty.getExample(), itemProperty.getType())}; + return new Object[]{itemProperty.getExample()}; } else if (itemProperty instanceof ArrayProperty) { return new Object[]{generateExampleForArrayProperty((ArrayProperty) itemProperty, definitions, markupDocBuilder)}; } else if (itemProperty instanceof RefProperty) { @@ -284,7 +284,7 @@ public class ExamplesUtil { public static Object[] generateExampleForArrayProperty(ArrayProperty value, Map definitions, MarkupDocBuilder markupDocBuilder) { Property property = value.getItems(); if (property.getExample() != null) { - return new Object[]{PropertyUtils.convertExample(property.getExample(), property.getType())}; + return new Object[]{property.getExample()}; } else if (property instanceof ArrayProperty) { return new Object[]{generateExampleForArrayProperty((ArrayProperty) property, definitions, markupDocBuilder)}; } else if (property instanceof RefProperty) { diff --git a/src/main/java/io/github/swagger2markup/internal/utils/PropertyUtils.java b/src/main/java/io/github/swagger2markup/internal/utils/PropertyUtils.java index cc1fa207..4f288e88 100644 --- a/src/main/java/io/github/swagger2markup/internal/utils/PropertyUtils.java +++ b/src/main/java/io/github/swagger2markup/internal/utils/PropertyUtils.java @@ -115,7 +115,7 @@ public final class PropertyUtils { Validate.notNull(property, "property must not be null"); Object examplesValue = null; if (property.getExample() != null) { - examplesValue = convertExample(property.getExample(), property.getType()); + examplesValue = property.getExample(); } else if (property instanceof MapProperty) { Property additionalProperty = ((MapProperty) property).getAdditionalProperties(); if (additionalProperty.getExample() != null) { diff --git a/src/main/java/io/github/swagger2markup/spi/DefinitionsDocumentExtension.java b/src/main/java/io/github/swagger2markup/spi/DefinitionsDocumentExtension.java index 6d7591e4..5089d5b8 100644 --- a/src/main/java/io/github/swagger2markup/spi/DefinitionsDocumentExtension.java +++ b/src/main/java/io/github/swagger2markup/spi/DefinitionsDocumentExtension.java @@ -28,6 +28,7 @@ public abstract class DefinitionsDocumentExtension extends AbstractExtension { public enum Position { DOCUMENT_BEFORE, + DOCUMENT_AFTER, DOCUMENT_BEGIN, DOCUMENT_END, DEFINITION_BEGIN, @@ -98,6 +99,9 @@ public abstract class DefinitionsDocumentExtension extends AbstractExtension { int levelOffset; switch (context.position) { case DOCUMENT_BEFORE: + case DOCUMENT_AFTER: + levelOffset = 0; + break; case DOCUMENT_BEGIN: case DOCUMENT_END: levelOffset = 1; diff --git a/src/main/java/io/github/swagger2markup/spi/OverviewDocumentExtension.java b/src/main/java/io/github/swagger2markup/spi/OverviewDocumentExtension.java index 91b85f03..6e674085 100644 --- a/src/main/java/io/github/swagger2markup/spi/OverviewDocumentExtension.java +++ b/src/main/java/io/github/swagger2markup/spi/OverviewDocumentExtension.java @@ -25,6 +25,7 @@ public abstract class OverviewDocumentExtension extends AbstractExtension { public enum Position { DOCUMENT_BEFORE, + DOCUMENT_AFTER, DOCUMENT_BEGIN, DOCUMENT_END } @@ -60,6 +61,9 @@ public abstract class OverviewDocumentExtension extends AbstractExtension { int levelOffset; switch (context.position) { case DOCUMENT_BEFORE: + case DOCUMENT_AFTER: + levelOffset = 0; + break; case DOCUMENT_BEGIN: case DOCUMENT_END: levelOffset = 1; diff --git a/src/main/java/io/github/swagger2markup/spi/PathsDocumentExtension.java b/src/main/java/io/github/swagger2markup/spi/PathsDocumentExtension.java index 7925094b..6e2b5919 100644 --- a/src/main/java/io/github/swagger2markup/spi/PathsDocumentExtension.java +++ b/src/main/java/io/github/swagger2markup/spi/PathsDocumentExtension.java @@ -17,8 +17,8 @@ package io.github.swagger2markup.spi; import com.google.common.base.Optional; -import io.github.swagger2markup.markup.builder.MarkupDocBuilder; import io.github.swagger2markup.GroupBy; +import io.github.swagger2markup.markup.builder.MarkupDocBuilder; import io.github.swagger2markup.model.PathOperation; import org.apache.commons.lang3.Validate; @@ -29,6 +29,7 @@ public abstract class PathsDocumentExtension extends AbstractExtension { public enum Position { DOCUMENT_BEFORE, + DOCUMENT_AFTER, DOCUMENT_BEGIN, DOCUMENT_END, OPERATION_BEGIN, @@ -88,6 +89,9 @@ public abstract class PathsDocumentExtension extends AbstractExtension { int levelOffset; switch (context.position) { case DOCUMENT_BEFORE: + case DOCUMENT_AFTER: + levelOffset = 0; + break; case DOCUMENT_BEGIN: case DOCUMENT_END: levelOffset = 1; diff --git a/src/main/java/io/github/swagger2markup/spi/SecurityDocumentExtension.java b/src/main/java/io/github/swagger2markup/spi/SecurityDocumentExtension.java index ee9711f4..c76d669f 100644 --- a/src/main/java/io/github/swagger2markup/spi/SecurityDocumentExtension.java +++ b/src/main/java/io/github/swagger2markup/spi/SecurityDocumentExtension.java @@ -28,6 +28,7 @@ public abstract class SecurityDocumentExtension extends AbstractExtension { public enum Position { DOCUMENT_BEFORE, + DOCUMENT_AFTER, DOCUMENT_BEGIN, DOCUMENT_END, DEFINITION_BEGIN, @@ -96,6 +97,9 @@ public abstract class SecurityDocumentExtension extends AbstractExtension { int levelOffset; switch (context.position) { case DOCUMENT_BEFORE: + case DOCUMENT_AFTER: + levelOffset = 0; + break; case DOCUMENT_BEGIN: case DOCUMENT_END: levelOffset = 1;