= Swagger2Markup
:author: Robert Winkler
:version: 0.1.0
:hardbreaks:

image:https://travis-ci.org/RobWin/swagger2asciidoc.svg["Build Status", link="https://travis-ci.org/RobWin/swagger2asciidoc"] image:https://coveralls.io/repos/RobWin/swagger2asciidoc/badge.svg["Coverage Status", link="https://coveralls.io/r/RobWin/swagger2asciidoc"] image:http://img.shields.io/:version-{version}-blue.svg["Semantic Versioning", link="http://semver.org"] image:http://img.shields.io/badge/license-ASF2-blue.svg["Apache License 2", link="http://www.apache.org/licenses/LICENSE-2.0.txt"]

WARNING: Still under heavy development

This project is a Swagger to Markup (AsciiDoc and Markdown) converter. It takes a swagger.json or swagger.yaml file as input and converts it into an AsciiDoc or Markdown file. The file can be located locally or remotely accessible via HTTP. The Swagger2Markup converter supports the Swagger 1.2 and 2.0 specification.

The primary goal of this project is to simplify the documentation of RESTful APIs. The result is intended to be an easy-to-read, on- and offline user guide, comparable to https://developer.github.com/v3/[GitHub's API documentation].

For example, you can generate your AsciiDoc/Markdown documentation using https://github.com/spring-projects/spring-boot[Spring Boot] and https://github.com/martypitt/swagger-springmvc[swagger-springmvc] as follows:

[source,java]
----
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = SpringBootSwaggerConfig.class)
@IntegrationTest
@WebAppConfiguration
public class Swagger2MarkupTest {

    @Test
    public void convertSwaggerToMarkup() {
        //Remote
        Swagger2MarkupConverter.from("http://localhost:8080/api-docs").
            toAsciiDoc("src/docs/asciidoc/example.adoc");

        Swagger2MarkupConverter.from("http://localhost:8080/api-docs").
            toMarkdown("src/docs/markdown/example.md");

        //Local
        File file = new File(Swagger2MarkupTest.class.getResource("/json/swagger.json").getFile());
        Swagger2MarkupConverter.from(file.getAbsolutePath()).toAsciiDoc("src/docs/asciidoc/swagger.adoc")
    }

}
----

[source,java]
----
@SpringBootApplication
@EnableSwagger
public class SpringBootSwaggerConfig {

    public static void main(String[] args) {
        SpringApplication.run(SpringBootTestConfig.class, args);
    }

    @Autowired
    private SpringSwaggerConfig springSwaggerConfig;

    @Bean
    public SwaggerSpringMvcPlugin customImplementation(){
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo()).excludeAnnotations(Controller.class);
    }

    private ApiInfo apiInfo() {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL"
        );
        return apiInfo;
    }
}
----

You can then generate HTML5 and PDF documentation via https://github.com/asciidoctor/asciidoctorj[asciidoctorj] or even better via the https://github.com/asciidoctor/asciidoctor-gradle-plugin[asciidoctor-gradle-plugin]
and https://github.com/aalmiray/markdown-gradle-plugin[markdown-gradle-plugin].

== Example
== swagger.json
image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/swagger_json.PNG[swagger_json]

=== Generated AsciiDoc file
image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc.PNG[asciidoc]

=== Generated Markdown file
image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/markdown.PNG[asciidoc]

=== Generated HTML
image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc_html.PNG[asciidoc_html]

== Document Builder
The converter allows to build an AsciiDoc or Markdown document via the Builder pattern:
[source,java]
----
        String asciiDoc = new AsciiDocBuilder().documentTitle("Title")
                .sectionTitleLevel1("Section1").paragraph("Text text")
                .sectionTitleLevel2("Code examples").listing("Code example").toString();

        String markdown = new MarkdownBuilder().documentTitle("Title")
                .sectionTitleLevel1("Section1").paragraph("Text text")
                .sectionTitleLevel2("Code examples").listing("Code example").toString();
----