Creating HTML documentation from Swagger specification via Maven is very easy. We just need to create a few scaffolding HTML files and use two Maven plugins:

We need to:

• put index.adoc into src/doc/asciidoc,
• create swagger.yaml and put it into main/swagger,
• configure pom.xml.
  • configure Swagger Maven plugin
  • configure Asciidoctor Maven plugin

Create index.adoc

Create index.adoc that will serve as a root (welcome) page:

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/definitions.adoc[]

The {generated} token is a variable that will be replaced by the proper path to the files.

Create swagger.yaml

Create Swagger specification file according to the reference documentation

Configure Maven plugins

We will need two Maven plugins:

• io.github.swagger2markup:swagger2markup-maven-plugin will generate AsciiDoc documentation from Swagger specification
• org.asciidoctor:asciidoctor-maven-plugin will generate HTML documentation from AsciiDoc markup.

Configuring Swagger2Markup

We will need to reference the Swagger specification file:

<swaggerInput>${project.basedir}/src/main/swagger/swagger.yaml</swaggerInput>

Furthermore, we need to output the Swagger AsciiDoc generated files directory:
${project.build.directory}/asciidoc

Configuring AsciiDoctor

We need to provide directory for static index.adoc file and directory:

 <sourceDirectory>src/doc/asciidoc</sourceDirectory>
 <sourceDocumentName>index.adoc</sourceDocumentName>

Then, we need to change default output format from DocBook to HTML5:

 <backend>html5</backend>

In the next step, we customize location of table of contents and define the value for {generated} variable used in the index.adoc.

 <attributes>
     <toc>left</toc>
     <generated>${project.build.directory}/asciidoc</generated>
 </attributes>

Running Maven

mvn clean swagger2markup:convertSwagger2markup asciidoctor:process-asciidoc

Complete pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>sk.projekt</groupId>
    <artifactId>projekt-swagger</artifactId>
    <version>1.0-SNAPSHOT</version>

    <dependencies>
        <dependency>
            <groupId>io.github.swagger2markup</groupId>
            <artifactId>swagger2markup</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>io.github.swagger2markup</groupId>
                <artifactId>swagger2markup-maven-plugin</artifactId>
                <version>1.0.0</version>
                <configuration>
                    <swaggerInput>${project.basedir}/src/main/swagger/swagger.yaml</swaggerInput>
                    <outputDir>${project.build.directory}/asciidoc</outputDir>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.asciidoctor</groupId>
                <artifactId>asciidoctor-maven-plugin</artifactId>
                <version>1.5.3</version>
                <configuration>
                    <sourceDirectory>src/doc/asciidoc</sourceDirectory>
                    <sourceDocumentName>index.adoc</sourceDocumentName>
                    <backend>html5</backend>
                    <attributes>
                        <toc>left</toc>
                        <generated>${project.build.directory}/asciidoc</generated>
                    </attributes>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <repositories>
        <repository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </repository>
    </repositories>

    <pluginRepositories>
        <pluginRepository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
        </pluginRepository>
        <pluginRepository>
            <snapshots>
                <enabled>false</enabled>
            </snapshots>
            <id>jcenter-releases</id>
            <name>jcenter</name>
            <url>http://jcenter.bintray.com</url>
        </pluginRepository>
    </pluginRepositories>
</project>