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
intosrc/doc/asciidoc
, - create
swagger.yaml
and put it intomain/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 specificationorg.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:
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>
42ff