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

The entry point of the Swagger2Markup API is the ``Swagger2MarkupConverter`` class. This class provides static factory methods to create a `Swagger2MarkupConverter.Builder`. 

[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=localSwaggerSpec]
----

1.  Create a ``Swagger2MarkupConverter.Builder`` by specifying the Path to the local file 
2.  Build an instance of the ``Swagger2MarkupConverter``
3.  Invoke ``toFolder`` by specifying the output directory


==== Conversion of  a remote Swagger file

You can convert a remote Swagger specification which must be accessible via HTTP.


[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=remoteSwaggerSpec]
----

1.  Create a ``Swagger2MarkupConverter.Builder`` by specifying the URL to the remote file
2.  Build an instance of the ``Swagger2MarkupConverter``
3.  Invoke ``toFolder`` by specifying the output directory


==== Conversion into a file

You can convert the Swagger specification into a file.

[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=convertIntoOneFile]
----

==== Conversion to a String

You can convert the Swagger specification to a String.


[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=convertIntoString]
----

=== Configuration

Swagger2Markup provides several options to configure the Swagger2MarkupConverter:

* Using system properties
* Using a fluent API
* Using a properties file
* Using a Java Map
* Using Apache Commons Configuration

==== 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.

[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupConfigBuilder]
----

1. Create a `Swagger2MarkupConfigBuilder` using the default constructor.
2. Configure the output `MarkupLanguage`
3. Configure the output `Language`
4. Configure additional Swagger2Markup properties
5. Build an instance of the `Swagger2MarkupConfig`
6. Use the custom Swagger2MarkupConfig

You can also create a `Swagger2MarkupConfig` from a Properties file, a `Map` or a Apache Commons Configuration.

==== Configuration from a Properties file

[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupConfigFromProperties]
----
1. Load a `Properties` file from the classpath or local filesystem.
2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.

==== Configuration from a Map

[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupConfigFromMap]
----

1. Create a `Map` and configure the `Swagger2MarkupProperties`.
2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.


==== Configuration from a Apache Commons Configuration

Configuration parameters may be loaded from the following sources using Apache Commons Configuration:

*   Properties files
*   XML documents
*   Property list files (plist)
*   JDBC Datasource
*   Servlet parameters

[source,java,indent=0]
----
include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=swagger2MarkupConfigFromCommonsConfiguration]
----

1. Create an Apache Commons `Configuration` object using the proper ConfigurationBuilder.
2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.

==== Swagger2Markup properties

The properties of Swagger2Markup are defined in the class `io.github.swagger2markup.Swagger2MarkupProperties`.
The properties are considered in the following order:

1. Java System properties
2. Custom properties
3. Default properties (included in Swagger2Markup)

The following tables list all available properties of Swagger2Markup:

[options="header"]
.Mostly used properties
|===
|Name | Description |  Possible Values | Default
|swagger2markup.markupLanguage| Specifies the markup language which should be used to generate the files. | ASCIIDOC, MARKDOWN, CONFLUENCE_MARKUP | ASCIIDOC
|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.generatedExamplesEnabled| Specifies if HTTP request and response examples should be generated | true, false | false
|===

[options="header"]
.Properties which configure the order of Swagger Objects
|===
|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 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
|===

[options="header"]
.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.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.securityDocument| Specifies the file name of the security document | Any String | "security"
|===

[options="header"]
.Properties which configure the generation of separate files
|===
|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 folder name | "operations"
|swagger2markup.separatedDefinitionsFolder| Specifies the target folder path for operation files | Any valid folder name | "definitions"
|===

[options="header"]
.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 for advanced usage | Any String | 
|swagger2markup.anchorPrefix| Optionally prefix all anchors for uniqueness | Any String | 
|===

[options="header"]
.Properties which configure inline schema rendering
|===
|Name | Description |  Possible Values | Default

|swagger2markup.inlineSchemaDepthLevel| Specifies maximum depth level for inline object schema displaying | Any Integer | 0
|swagger2markup.flatBodyEnabled| Optionally isolate the body parameter, if any, from other parameters | true, false | false
|===

=== Logging

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.
