= swagger2AsciiDoc
This project is a Swagger to AsciiDoc converter. It takes an swagger.json or swagger.yaml as an input file 
and generates an AsciiDoc file. 
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 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 Swagger2AsciiDocTest {

    @Test
    public void convertSwaggerToAsciiDoc() {
        Swagger2AsciiDocConverter.newInstance("http://localhost:8080/api-docs", "src/docs/asciidoc/example.adoc").convertSwagger2AsciiDoc();
    }

}
----

[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].

== 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 HTML
image::https://github.com/RobWin/swagger2AsciiDoc/blob/master/images/asciidoc_html.PNG[asciidoc_html]

== Build
The project is build and tested with Travis CI. Build status of master branch is:

image:https://travis-ci.org/RobWin/swagger2asciidoc.svg["Build Status", link="https://travis-ci.org/RobWin/swagger2asciidoc"]

== License
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.