Swagger2Markup

Free plan APILinuxSelf-hosted

What Swagger2Markup is

Swagger2Markup is a free, open-source JAR library for producing REST API guides from Swagger documentation. It accepts Swagger JSON or YAML files stored locally or reachable over HTTP, then converts them into AsciiDoc, GitHub Flavored Markdown, or Atlassian Confluence Wiki documents. By default, it creates separate overview, paths, security, and definitions files, while other modes write one file or return documentation as a string. Configuration covers markup and output language, path grouping, generated examples, and document ordering. Extension points allow changes to those document sections and to the Swagger model before conversion. The project documents integrations with Swagger JAX-RS, Springfox, Spring REST Docs, and Gradle or Maven plugins. Asciidoctor tools can turn AsciiDoc output into HTML, PDF, or EPUB. Swagger2Markup supports Swagger 1.2 and 2.0 and requires at least JDK 8. It is self-hosted, licensed under Apache License 2.0, and includes command-line and Docker documentation.

Who it suits

Swagger2Markup suits developers who need self-hosted generation of REST API documentation from Swagger files. It is useful when output must be customized or delivered in several documentation formats.

What it does well

Free and open source
Supports Swagger JSON and YAML
Multiple documentation output formats
Custom extension points
Self-hosted deployment

What to know first

Requires at least JDK 8
Supports Swagger 1.2 and 2.0 specifications
Maintainer seeks help with Swagger v3 support

Verdict

Swagger2Markup provides configurable, self-hosted conversion from Swagger specifications into several documentation formats. Its documented compatibility is limited to Swagger 1.2 and 2.0, and the project’s maintainer says additional help is needed.

Facts from Swagger2Markup's own pages

Build output: AsciiDoc output can be converted to HTML, PDF, and EPUB using Asciidoctor tooling. · github.com, 9 Oct 2026
CLI and Docker: The reference documentation includes command-line usage and a Docker image section. · swagger2markup.github.io, 9 Oct 2026
Compatibility limit: The project README says it supports Swagger 1.2 and 2.0 specifications and requires at least JDK 8. · github.com, 4 Oct 2026
Configuration: Options include output markup language, output language, path grouping, generated examples, and document ordering. · swagger2markup.github.io, 9 Oct 2026
Conversion options: The converter can write output to a folder, write a single file, or return documentation as a string. · swagger2markup.github.io, 4 Oct 2026
Customization: It provides extension points for overview, paths, security, and definitions documents, and for modifying the Swagger model before conversion. · swagger2markup.github.io, 4 Oct 2026
Distribution: The documentation describes Swagger2Markup as a JAR library published in JCenter and Maven Central. · swagger2markup.github.io, 9 Oct 2026
Extensions: An extension SPI supports extending overview, paths, security, and definitions documents, and modifying the Swagger model before conversion. · swagger2markup.github.io, 9 Oct 2026
Formats: The documentation says AsciiDoc output can be converted to HTML, PDF, and EPUB using Asciidoctor tools. · swagger2markup.github.io, 4 Oct 2026
Generated documentation: By default, it generates four AsciiDoc files for overview, paths, security, and definitions, and can instead produce one file or a string. · swagger2markup.github.io, 4 Oct 2026
Input and output: It converts Swagger JSON or YAML into AsciiDoc, GitHub Flavored Markdown, or Atlassian Confluence Wiki documents. · swagger2markup.github.io, 4 Oct 2026
Input location: The Swagger specification can be read from a local file or a remote URL accessible over HTTP. · swagger2markup.github.io, 9 Oct 2026
Integrations: The project documents use with Swagger JAX-RS, Springfox, Spring REST Docs, and Gradle and Maven plugins. · swagger2markup.github.io, 9 Oct 2026
License: The project is licensed under Apache License 2.0. · github.com, 9 Oct 2026
Maintenance: The README says the maintainer can no longer maintain the project alone and lists Swagger v3 support and bug fixes among topics needing help. · github.com, 4 Oct 2026
Maintenance status: The maintainer says they can no longer maintain the project alone and welcomes community help, including work on Swagger v3 support and bug fixes. · github.com, 9 Oct 2026
Output formats: It converts Swagger JSON or YAML into AsciiDoc, GitHub Flavored Markdown, or Atlassian Confluence Wiki documents. · swagger2markup.github.io, 9 Oct 2026
Output options: The converter can generate separate overview, paths, security, and definitions files, or produce one file or a string. · swagger2markup.github.io, 9 Oct 2026
Purpose: Swagger2Markup combines handwritten material with automatically generated API documentation to produce an up-to-date REST API guide. · github.com, 9 Oct 2026
Runtime requirement: The project requires at least JDK 8. · github.com, 9 Oct 2026
Support: The project README directs questions to Gitter and asks users to report bugs and enhancement requests through GitHub issues and pull requests. · github.com, 9 Oct 2026

Where Swagger2Markup stands on Freedom251

API Documentation Tools#25 of 27