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 GitHub’s API documentation.
For example, you can generate your AsciiDoc documentation using Spring Boot and swagger-springmvc as follows:
@RunWith(SpringJUnit4ClassRunner.class)
@SpringApplicationConfiguration(classes = SpringBootSwaggerConfig.class)
@IntegrationTest
@WebAppConfiguration
public class Swagger2AsciiDocTest {
@Test
public void convertSwaggerToAsciiDoc() {
Swagger2AsciiDocConverter.from("http://localhost:8080/api-docs")
.convertTo("src/docs/asciidoc/swagger.adoc");
}
}@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 asciidoctorj or even better via the asciidoctor-gradle-plugin.
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.