198 lines
8.4 KiB
Plaintext
198 lines
8.4 KiB
Plaintext
== 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.
|