mindol1004/swagger2markup
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
Robert Winkler
2016-04-06 08:12:07 +02:00
parent 310a2e47b6
commit df23dc09e8
4 changed files with 32 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
src/docs/asciidoc/demo.adoc
View File

@@ -2,11 +2,12 @@
If you use Spring Boot and Springfox or Swagger JAX-RS, you can do the following: 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 * convert the Swagger JSON file into AsciiDoc
* add hand-written AsciiDoc documentation * add hand-written AsciiDoc documentation
* convert AsciiDoc into HTML and PDF * 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 * 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. 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``. 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] [source,java]
---- ----
@RunWith(SpringJUnit4ClassRunner.class) @RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = Application.class) @SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
@WebIntegrationTest @WebIntegrationTest
public class Swagger2MarkupTest { 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. 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] [source,java]
---- ----
@WebAppConfiguration @WebAppConfiguration
@RunWith(SpringJUnit4ClassRunner.class) @RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = Application.class, loader = SpringApplicationContextLoader.class) @SpringApplicationConfiguration(classes = {Application.class, SwaggerConfig.class})
public class Swagger2MarkupTest { public class Swagger2MarkupTest {
@Autowired @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: If you want to start the Spring Boot application, please run:

20
src/docs/asciidoc/extension_spi.adoc
View File

@@ -1,24 +1,24 @@
== Extension SPI == 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"] [options="header"]
.Swagger2Markup extensions points .Swagger2Markup extensions
|==== |====
| Name | Class | Description | Name | Class | Description
| ``OverviewDocumentExtension`` | io.github.swagger2markup.spi.OverviewDocumentExtension | Can be used to extend the content of the Overview document | <<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 | <<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 | <<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 | <<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 | <<SwaggerModelExtension>> | io.github.swagger2markup.spi.SwaggerModelExtension | Can be used to modify the Swagger model before it is converted
|==== |====
=== Creation of an extension === 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 * `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 point. * `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] [source,java,indent=0]
---- ----

6
src/docs/asciidoc/getting_started.adoc
View File

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

28
src/docs/asciidoc/usage_guide.adoc
View File

@@ -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. 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`. 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 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. 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 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. 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] 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. 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] include::../../test/java/io/github/swagger2markup/DocumentationTest.java[tags=convertIntoString]
---- ----
== Configuration of Swagger2Markup === Configuration
Swagger2Markup provides several options to configure the Swagger2MarkupConverter: 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 a Java Map
* Using Apache Commons Configuration * 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. 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. 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] [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. 1. Load a `Properties` file from the classpath or local filesystem.
2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor. 2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor.
=== Configuration from a Map ==== Configuration from a Map
[source,java,indent=0] [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. 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: 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. 1. Create an Apache Commons `Configuration` object using the proper ConfigurationBuilder.
2. Create a `Swagger2MarkupConfigBuilder` using the proper constructor. 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 of Swagger2Markup are defined in the class `io.github.swagger2markup.Swagger2MarkupProperties`.
The properties are considered in the following order: 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 |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.