Updated documentation

src/docs/asciidoc/demo.adoc

@@ -2,11 +2,12 @@
 
 If you use Spring Boot and Springfox or Swagger JAX-RS, you can do the following:
 
-*   generate an up-to-date Swagger JSON file during an integration
+*   generate an up-to-date Swagger JSON file during an unit or integration test
 *   convert the Swagger JSON file into AsciiDoc
 *   add hand-written AsciiDoc documentation
 *   convert AsciiDoc into HTML and PDF
 *   copy the HTML and PDF artifacts into an executable Spring Boot Jar file and serve it as static content
+
 This transformation pipeline can be done with Gradle or Maven in the build phase. That way there is no runtime overhead and there are no additional runtime libraries required.
 
 The Swagger2MarkupConverter can be used to make a request to a remote Swagger endpoint during an integration test. The Swagger2MarkupConverter allows to write the generated documents into any folder. In this this example it is ``src/docs/asciidoc/generated``.
@@ -14,7 +15,7 @@ The Swagger2MarkupConverter can be used to make a request to a remote Swagger en
 [source,java]
 ----
 @RunWith(SpringJUnit4ClassRunner.class)
-@SpringApplicationConfiguration(classes = Application.class)
+@SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
 @WebIntegrationTest
 public class Swagger2MarkupTest {
 
@@ -28,12 +29,13 @@ public class Swagger2MarkupTest {
 ----
 
 Spring's MVC Test framework can also be used to make a request to a Springfox Swagger endpoint during an unit test. A custom ResultHandler ``Swagger2MarkupResultHandler`` can be used to write the Swagger JSON response into a directory. The custom ResultHandler is part of ``springfox-staticdocs``. That way you also verify that your Swagger endpoint is working.
+The Swagger JSON response can be converted using the <<Gradle Plugin>> or <<Maven Plugin>>.
 
 [source,java]
 ----
 @WebAppConfiguration
 @RunWith(SpringJUnit4ClassRunner.class)
-@ContextConfiguration(classes = Application.class, loader = SpringApplicationContextLoader.class)
+@SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
 public class Swagger2MarkupTest {
 
     @Autowired
@@ -57,9 +59,9 @@ public class Swagger2MarkupTest {
 }
 ----
 
-The quickest way to get started is to look at the demo project https://github.com/Swagger2Markup/spring-swagger2markup-demo[spring-swagger2markup-demo]. The demo shows how to generate static docs (HTML5 and PDF) with the Swagger2Markup Gradle Plugin and serve them as static content in a Spring Boot App under http://localhost:9080/docs/index.html and http://localhost:9080/docs/index.pdf.
+=== Demo
 
-=== Full example
+The quickest way to get started is to look at the demo project https://github.com/Swagger2Markup/spring-swagger2markup-demo[spring-swagger2markup-demo]. The demo shows how to generate static docs (HTML5 and PDF) by using the Swagger2Markup Gradle Plugin and serve the generated documentation as static content in a Spring Boot App under http://localhost:9080/docs/index.html and http://localhost:9080/docs/index.pdf.
 
 If you want to start the Spring Boot application, please run:
 

src/docs/asciidoc/extension_spi.adoc

@@ -1,24 +1,24 @@
 == Extension SPI
 
-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.
+Swagger2Markup provides an Extension SPI to extend the functionality of Swagger2Markup. Five types of extension are available. An extension is an abstract class which must be implemented.
 
 [options="header"]
-.Swagger2Markup extensions points
+.Swagger2Markup extensions
 |====
 | Name | Class | Description
-| ``OverviewDocumentExtension`` | io.github.swagger2markup.spi.OverviewDocumentExtension | Can be used to extend the content of the Overview document
-| ``PathsDocumentExtension`` | io.github.swagger2markup.spi.PathsDocumentExtension | Can be used to extend the content of the Paths document
-| ``SecurityDocumentExtension`` | io.github.swagger2markup.spi.SecurityDocumentExtension | Can be used to extend the content of the Security document
-| ``DefinitionsDocumentExtension`` | io.github.swagger2markup.spi.DefinitionsDocumentExtension | Can be used to extend the content of the Definitions document
-| ``SwaggerModelExtension`` | io.github.swagger2markup.spi.SwaggerModelExtension | Can be used to modify the Swagger model before it is converted
+| <<OverviewDocumentExtension>> | io.github.swagger2markup.spi.OverviewDocumentExtension | Can be used to extend the content of the Overview document
+| <<PathsDocumentExtension>> | io.github.swagger2markup.spi.PathsDocumentExtension | Can be used to extend the content of the Paths document
+| <<SecurityDocumentExtension>> | io.github.swagger2markup.spi.SecurityDocumentExtension | Can be used to extend the content of the Security document
+| <<DefinitionsDocumentExtension>> | io.github.swagger2markup.spi.DefinitionsDocumentExtension | Can be used to extend the content of the Definitions document
+| <<SwaggerModelExtension>> | io.github.swagger2markup.spi.SwaggerModelExtension | Can be used to modify the Swagger model before it is converted
 |====
 
 === 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`. Every extension point provides to methods which must be implemented: 
+To create a custom extension, you have to create a class (e.g. `io.myname.MyExtension`) which extends an extension, e.g. `io.github.swagger2markup.spi.DefinitionsDocumentExtension`. Every extension point provides two 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.
+* `init`: This method is invoked once and can be used to initialize the extension.
+* `apply`: This method is invoked multiple times depending on the type of the extension. The `Position` can be retrieved from the `Context` and can be used to extend the document at specific extension points.
 
 [source,java,indent=0]
 ----

src/docs/asciidoc/getting_started.adoc

@@ -67,11 +67,5 @@ repositories {
 </repositories>
 ----
 
-=== SBT
-==== Release
 
-[source, subs="specialcharacters,attributes"]
-----
-libraryDependencies += "io.github.swagger2markup" % "swagger2markup" % "{project-version}"
-----
 

src/docs/asciidoc/usage_guide.adoc

@@ -1,9 +1,11 @@
-== Usage guide
+== Swagger2Markup API
+
+=== Usage guide
 
 Swagger2Markup converts a Swagger JSON or YAML specification into either **AsciiDoc**, **GitHub Flavored Markdown** or **Atlassian Confluence Wiki** documents. By default the Swagger2Markup converts a Swagger specification into four AsciiDoc files: __overview.adoc__, __paths.adoc__ , __security.adoc__ and __definitions.adoc__. But you can also convert a Swagger specification into only one file or a String.
 
 
-=== Conversion of a local Swagger file
+==== Conversion of a local Swagger file
 
 The entry point of the Swagger2Markup API is the ``Swagger2MarkupConverter`` class. This class provides static factory methods to create a `Swagger2MarkupConverter.Builder`. 
 
@@ -17,7 +19,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=lo
 3.  Invoke ``toFolder`` by specifying the output directory
 
 
-=== Conversion of  a remote Swagger file
+==== Conversion of  a remote Swagger file
 
 You can convert a remote Swagger specification which must be accessible via HTTP.
 
@@ -32,7 +34,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=re
 3.  Invoke ``toFolder`` by specifying the output directory
 
 
-=== Conversion into a file
+==== Conversion into a file
 
 You can convert the Swagger specification into a file.
 
@@ -41,7 +43,7 @@ You can convert the Swagger specification into a file.
 include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=convertIntoOneFile]
 ----
 
-=== Conversion to a String
+==== Conversion to a String
 
 You can convert the Swagger specification to a String.
 
@@ -51,7 +53,7 @@ You can convert the Swagger specification to a String.
 include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=convertIntoString]
 ----
 
-== Configuration of Swagger2Markup
+=== Configuration
 
 Swagger2Markup provides several options to configure the Swagger2MarkupConverter:
 
@@ -61,7 +63,7 @@ Swagger2Markup provides several options to configure the Swagger2MarkupConverter
 * Using a Java Map
 * Using Apache Commons Configuration
 
-=== Configuration using the Builder
+==== Configuration using the Builder
 
 You can configure the Swagger2MarkupConverter by using the `Swagger2MarkupConfigBuilder` to build a custom `Swagger2MarkupConfig`. The `Swagger2MarkupConfigBuilder` can be used to define Swagger2Markup properties with a fluent API.
 
@@ -79,7 +81,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=sw
 
 You can also create a `Swagger2MarkupConfig` from a Properties file, a `Map` or a Apache Commons Configuration.
 
-=== Configuration from a Properties file
+==== Configuration from a Properties file
 
 [source,java,indent=0]
 ----
@@ -88,7 +90,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=sw
 1. Load a `Properties` file from the classpath or local filesystem.
 2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.
 
-=== Configuration from a Map
+==== Configuration from a Map
 
 [source,java,indent=0]
 ----
@@ -99,7 +101,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=sw
 2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.
 
 
-=== Configuration from a Apache Commons Configuration
+==== Configuration from a Apache Commons Configuration
 
 Configuration parameters may be loaded from the following sources using Apache Commons Configuration:
 
@@ -117,7 +119,7 @@ include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=sw
 1. Create an Apache Commons `Configuration` object using the proper ConfigurationBuilder.
 2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.
 
-=== Swagger2Markup properties
+==== Swagger2Markup properties
 
 The properties of Swagger2Markup are defined in the class `io.github.swagger2markup.Swagger2MarkupProperties`.
 The properties are considered in the following order:
@@ -190,6 +192,6 @@ The following tables list all available properties of Swagger2Markup:
 |swagger2markup.flatBodyEnabled| Optionally isolate the body parameter, if any, from other parameters | true, false | false
 |===
 
-== Logging
+=== Logging
 
-Swagger2Markup uses http://www.slf4j.org/[SLF4J] for all internal logging, but leaves the underlying log implementation open.
+Swagger2Markup uses http://www.slf4j.org/[SLF4J] for all internal logging, but leaves the underlying log implementation open. To change the log level, you have the set the log level of the `io.github.swagger2markup` package.