== 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::{coreProjectDir}/src/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::{coreProjectDir}/src/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::{coreProjectDir}/src/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::{coreProjectDir}/src/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::{coreProjectDir}/src/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::{coreProjectDir}/src/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::{coreProjectDir}/src/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::{coreProjectDir}/src/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, REGEX | 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.flatBodyEnabled| Optionally isolate the body parameter, if any, from other parameters | true, false | false
|swagger2markup.pathSecuritySectionEnabled| Optionally disable the security section for path sections | true, false | true
|swagger2markup.anchorPrefix| Optionally prefix all anchors for uniqueness if you want to include generated documents into a global documentation | Any String |
|swagger2markup.basePathPrefixEnabled| Prepend the basePath to all paths | true, false | false
|swagger2markup.headerRegex | Regular expression to use when grouping by RegEx | Any valid RegEx pattern with at least one capture group |
|===

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

[options="header"]
.Properties which configure inline schema rendering
|===
|Name | Description |  Possible Values | Default
|swagger2markup.inlineSchemaEnabled| Enable inline object schema support | true, false | true
|===

[options="header"]
.Properties which configure page breaking
|===
|Name | Description | Possible Values | Default
|swagger2markup.pageBreakLocations | Specifies where page breaks should be inserted. | BEFORE_OPERATION, BEFORE_OPERATION_DESCRIPTION, BEFORE_OPERATION_PARAMETERS, BEFORE_OPERATION_RESPONSES, BEFORE_OPERATION_CONSUMES, BEFORE_OPERATION_PRODUCES, BEFORE_OPERATION_EXAMPLE_REQUEST, BEFORE_OPERATION_EXAMPLE_RESPONSE, BEFORE_DEFINITION, AFTER_OPERATION, AFTER_OPERATION_DESCRIPTION, AFTER_OPERATION_PARAMETERS, AFTER_OPERATION_RESPONSES, AFTER_OPERATION_CONSUMES, AFTER_OPERATION_PRODUCES, AFTER_OPERATION_EXAMPLE_REQUEST, AFTER_OPERATION_EXAMPLE_RESPONSE, AFTER_DEFINITION | empty
|===


[options="header"]
.Properties which configure examples generation
|===
|Name |Description |Possible Values |Default

|swagger2markup.generatedExamplesEnabled
| Specifies if HTTP request and response examples should be generated
| true, false
| false

|swagger2markup.requestExamplesFormat
| Specifies if `Request path` contents in `Example HTTP request` section should contain popular example utility
invocation, e.g. `curl`
a|
* `basic` — example will have only endpoint and query params
* `curl` — example with `curl` utility
* `invoke-webrequest` — example with `Invoke-WebRequest` command of `powershell`
| basic

|swagger2markup.requestExamplesSourceFormat
|`Request path` source block code style format
| `default` or any suppordet by asciidoc
| none for `basic`, `bash` for `curl` and `powershell` for `WebRequest`

|swagger2markup.requestExamplesIncludeAllQueryParams
|Specifies if `Request path` should contain required and optional params (if true) or only required (if false)
|true, false
|false

|swagger2markup.requestExamplesHost
|Should we hide, inherit or override hostname (e.g. with google.com) from  yml file
|`hide`, `inherit` or string with hostname to be used in request example
| hide

|swagger2markup.requestExamplesSchema
|Should we hide, inherit or override schema (http, https name it) from yml file
|`hide`, `inherit` or string with schema name to be used in request example
| hide

|swagger2markup.requestExamplesHideBasePath
|Should we hide or show base path in example request endpoint address
|true, false
|true

|swagger2markup.requestExamplesQueryArrayStyle
|How we should output array query params
|`single` —  single time (similar to basic types), `commaSeparated` — single time with multiple comma separated values, `multiple` times with same param name and different values, `multiple[]` times with array brackets as param name suffix.
|single


|===

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