Updated documentation

src/docs/asciidoc/extension_spi.adoc

@@ -3,7 +3,7 @@
 Swagger2Markup provides an Extension SPI to extend the functionality of Swagger2Markup. Five types of extension points are available. Each extension point is an abstract class which must be implemented.
 
 [options="header"]
-.Swagger2Markup Extensions points
+.Swagger2Markup extensions points
 |====
 | Name | Class | Description
 | ``OverviewDocumentExtension`` | io.github.swagger2markup.spi.OverviewDocumentExtension | Can be used to extend the content of the Overview document
@@ -24,6 +24,10 @@ To create a custom extension, you have to create a class (e.g. `io.myname.MyExte
 ----
 include::../../test/java/io/github/swagger2markup/builder/MyExtension.java[tags=MyExtension]
 ----
+1. You can retrieve extension properties from the config to configure the extension.
+2. You can retrieve a `MarkupDocBuilder` from the `Context`.
+3. You can retrieve the current `Position` from the Context.
+4. You can use a `MarkupDocBuilder` to add Markup using a fluent API or import Markup from files.
 
 === Registration of an extension 
 
@@ -112,9 +116,136 @@ The SwaggerModelExtension allows to modify the Swagger model before it is proces
 
 === Provided Extensions
 
-Swagger2Markup provides some extensions which can be used out-of-the-box.
+Swagger2Markup provides some extensions which can be used out-of-the-box. You just have to add the extension to your classpath.
+
+[options="header"]
+.Swagger2Markup extensions
+|====
+| Name | Description
+| <<Dynamic file import extension>> | Allows to dynamically import Markup from files.
+| <<Spring RestDocs extension>> | Allows to import example Curl, HTTP request and response snippets from Spring Rest Docs.
+| <<Schema file import extension>> | Allows to import JSON or XML Schema files.
+|====
+
+==== Dynamic file import extension
+
+===== Usage guide
+
+[source,groovy, subs="attributes"]
+----
+repositories {
+    jCenter()
+}
+
+compile "io.github.swagger2markup:swagger2markup-import-files-ext:{project-version}"
+----
+
+The extension searches for markup files in configurable paths to append the markup to the documents. The markup files must conform to a naming convention to be found. The files must start with the position where the document should be extended and end with the markup file extension (e.g `adoc` or `md`). See documentation of <<Extensions points>>.
+
+All documents:
+
+* `document-before-*.<markup.ext>`
+* `document-after-*.<markup.ext>`
+* `document-begin-*.<markup.ext>`
+* `document-end-*.<markup.ext>`
+
+Paths document:
+
+* `operation-begin-*.<markup.ext>`
+* `operation-end-*.<markup.ext>`
+
+Definitions and Security document:
+
+* `defintion-begin-*.<markup.ext>`
+* `defintion-begin-*.<markup.ext>`
+
+===== Configuration
+
+The extension adds the following properties to Swagger2Markup which must be configured:
+
+[options="header"]
+.Extension properties
+|====
+| Name | Description | Example
+| `swagger2markup.extensions.dynamicOverview.contentPath`  | The path to the files which should be imported into the Overview document | `src/test/resources/docs/asciidoc/overview` 
+| `swagger2markup.extensions.dynamicDefinitions.contentPath`  | The path to the files which should be imported into the Definitions document | `src/test/resources/docs/asciidoc/definitions` 
+| `swagger2markup.extensions.dynamicPaths.contentPath`  | The path to the files which should be imported into the Paths document | `src/test/resources/docs/asciidoc/paths` 
+| `swagger2markup.extensions.dynamicSecurity.contentPath`  | TThe path to the files which should be imported into the Security document | `src/test/resources/docs/asciidoc/security` 
+|====
+
+==== Spring RestDocs extension
+
+===== Usage guide
+
+[source,groovy, subs="attributes"]
+----
+repositories {
+    jCenter()
+}
+
+compile "io.github.swagger2markup:swagger2markup-spring-restdocs-ext:{project-version}"
+----
+
+The extension searches for Spring RestDocs snippet files in a configurable path to append the snippets at the end of a path operation section. The snippet files must be called: 
+
+* http-request.<markup.ext>`
+* http-response.<markup.ext>`
+* curl-request.<markup.ext>`
+
+The files must be stored in a folder which matches the Swagger operationId.
+
+Swagger Example:
+
+[source]
+----
+paths:
+  /pets:
+    post:
+      summary: Add a new pet to the store
+      operationId: addPet
+      ...
+----
+
+Example: `/snippets/addPet/http-request.adoc`.
+
+===== Configuration
+
+The extension adds the following properties to Swagger2Markup which must be configured:
+
+[options="header"]
+.Extension properties
+|====
+| Name | Description | Example
+| `swagger2markup.extensions.springRestDocs.snippetBaseUri`  | The path to the Spring RestDocs snippets | `src/test/resources/docs/asciidoc/paths` 
+|====
+
+==== Schema file import extension
+
+===== Usage guide
+
+[source,groovy, subs="attributes"]
+----
+repositories {
+    jCenter()
+}
+
+compile "io.github.swagger2markup:swagger2markup-import-schemas-ext:{project-version}"
+----
+
+The extension searches for Schema files in a configurable path to append the Schema file content at the end of a definition section. The Schema files must conform to a naming convention to be found. The files must be called `schema.xsd` or `schema.json` and must be stored in a folder which matches the name of a definition. 
+
+Example: `/schemas/Pet/schema.json`.
+
+
+===== Configuration
+
+The extension adds the following properties to Swagger2Markup which must be configured:
+
+[options="header"]
+.Extension properties
+|====
+| Name | Description | Example
+| `swagger2markup.extensions.schema.schemaBaseUri`  | The path to the schema files | `src/test/resources/docs/asciidoc/schemas` 
+|====
 
-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.
 

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

@@ -18,10 +18,13 @@ package io.github.swagger2markup.builder;
 import io.github.swagger2markup.Swagger2MarkupConverter;
 import io.github.swagger2markup.Swagger2MarkupProperties;
 import io.github.swagger2markup.markup.builder.MarkupDocBuilder;
+import io.github.swagger2markup.markup.builder.MarkupLanguage;
 import io.github.swagger2markup.spi.DefinitionsDocumentExtension;
 import io.swagger.models.Model;
 import io.swagger.models.Swagger;
 
+import java.io.StringReader;
+
 // tag::MyExtension[]
 public class MyExtension extends DefinitionsDocumentExtension {
 
@@ -31,18 +34,24 @@ public class MyExtension extends DefinitionsDocumentExtension {
     @Override
     public void init(Swagger2MarkupConverter.Context globalContext) {
         // init is executed once
-        Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties();
+        Swagger2MarkupProperties extensionProperties = globalContext.getConfig().getExtensionsProperties(); //<1>
         extensionProperty = extensionProperties.getRequiredString(EXTENSION_ID + ".propertyName");
         Swagger model = globalContext.getSwagger();
     }
 
     @Override
     public void apply(Context context) {
-        MarkupDocBuilder markupBuilder = context.getMarkupDocBuilder();
+        MarkupDocBuilder markupBuilder = context.getMarkupDocBuilder(); //<2>
-        Position position = context.getPosition();
+        Position position = context.getPosition(); //<3>
         String definitionName = context.getDefinitionName().get();
         Model definitionModel = context.getModel().get();
 
+        if(position.equals(Position.DEFINITION_END)) {
+            markupBuilder.sectionTitleLevel4(definitionName) //<4>
+                    .paragraph(definitionModel.getDescription())
+                    .importMarkup(new StringReader("*Markup*"), MarkupLanguage.ASCIIDOC);
+        }
+
         // apply is executed per definition
     }
 }