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