Preferred way to convert openapi 3 document (json or yaml) to markdown, adoc or any other static format

Question

I try to find an easy way in java to convert an openapi 3 document (json or yaml) in a static format like markdown, html or adoc. Searching around I've found a view projects like Swagger2Markup, but they aren't ready for Openapi v3!

Does anyone have any advice or an hint for a library or maven plugin for me?

score 0 · Answer 1 · answered Sep 07 '22 at 10:59

You may need to check the project https://github.com/Mermade/widdershins It is a good tool that converts from Openapi specs to markdown. it is an npm module, and it is generating markdown to use on Redoc, but you can still customize the generated template

score 0 · Accepted Answer · answered Sep 25 '22 at 09:08

I've found the correct maven plugin to do this:

<plugin>
    <!-- converts the openapi docu to html -->
    <groupId>io.swagger.codegen.v3</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>3.0.35</version>
    <executions>
        <execution>
            <id>export-opennapi-to-html-doc</id>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
               <inputSpec>${project.build.directory}/api.yml</inputSpec>
               <language>html2</language>
               <output>${project.basedir}/docs</output>
             </configuration>
         </execution>
    </executions>
</plugin>

Preferred way to convert openapi 3 document (json or yaml) to markdown, adoc or any other static format

2 Answers2