Convert Swagger Docs to Markdown and Confluence with Swagger2Markup

Swagger2Markup Overview

Swagger2Markup is an open‑source Java library that converts Swagger/OpenAPI specifications into several documentation formats such as AsciiDoc, Markdown and Confluence markup, making it easy to publish static API docs.

Generating Markdown and Confluence

Both formats are produced by adjusting a single configuration property. The withMarkupLanguage method selects the target format and toFolder defines the output directory.

Java code for Markdown

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/markdown/generated"));

Java code for Confluence

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/confluence/generated"));

After execution the src/docs directory contains separate sub‑folders for Markdown and Confluence, each with generated files such as definitions.md, overview.md, paths.md, security.md (or the corresponding .txt files for Confluence).

Single‑File Output

If a single consolidated file is preferred, replace the toFolder(...) call with toFile(Paths.get("src/docs/asciidoc/generated/all")). The converter will write all sections into one file, which can later be transformed into a single HTML page.

Static Deployment

Markdown output can be served with any static site generator (e.g., Hexo, Jekyll). For Confluence, copy the generated .txt content into a Confluence page using the {} markup macro and the “ConfluenceWiki” insert option, as shown in the screenshots.

Confluence Insertion Steps

Open a new Confluence page and click the {} markup button.

Choose “Insert → ConfluenceWiki”.

Paste the generated text into the left pane; the rendered view appears on the right.