easily generate docs and playground for your RESTful API
This is useful when you want to distribute your documentation to people that do not have access to the server hosting your API (and your JSONDoc endpoint). You will need to use the jsondoc-maven-plugin
and then play a bit with other maven plugins. Let's see how this can be done:
jsondoc-maven-plugin
<plugin>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-jsondoc</id>
<phase>package</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<version>4.1</version>
<basePath>http://localhost:8080/api</basePath>
<packages>
<package>org.jsondoc.sample.controller</package>
<package>org.jsondoc.sample.pojo</package>
<package>com.sample</package>
</packages>
<outputFile>${project.build.directory}/jsondoc-ui/jsondoc.json</outputFile>
<scanner>org.jsondoc.springmvc.scanner.SpringJSONDocScanner</scanner>
</configuration>
</execution>
</executions>
</plugin>
jsondoc-ui
dependency<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>unpack</id>
<phase>process-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-ui</artifactId>
<type>jar</type>
<overWrite>true</overWrite>
<outputDirectory>${project.build.directory}/jsondoc-ui</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<executions>
<execution>
<id>create-distribution</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<finalName>jsondoc</finalName>
<descriptors>
<descriptor>assembly/jsondoc-assembly.xml</descriptor>
</descriptors>
</configuration>
</execution>
</executions>
</plugin>
This is the assembly descriptor to be used:
<?xml version="1.0" encoding="UTF-8"?>
<assembly
xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd">
<id>distribution</id>
<formats>
<format>zip</format>
</formats>
<fileSets>
<fileSet>
<outputDirectory>/</outputDirectory>
<directory>${project.build.directory}/jsondoc-ui</directory>
<filtered>true</filtered>
<excludes>
<exclude>**/META-INF/**</exclude>
</excludes>
</fileSet>
</fileSets>
<includeBaseDirectory>false</includeBaseDirectory>
</assembly>
Note the presence of the filtered
tag. This means that everything in the specified directory will be filtered with properties defined in the pom file. For example, to correctly display a value in the input box at the top of the JSONDoc UI, you may want to filter the ${jsondoc.path}
placeholder (in jsondoc-ui.html
) with the filename generated by the jsondoc-maven-plugin. Here is a part of the pom file showing the properties section for both an online generation of the documentation and a distributable one:
<properties>
<jsondoc.path>http://localhost:8080/api/jsondoc</jsondoc.path>
</properties>
<profiles>
<profile>
<id>distributable</id>
<properties>
<jsondoc.path>jsondoc.json</jsondoc.path>
</properties>
</profile>
</profiles>
The result of the mvn clean package -Pdistributable
command will be a zip containing the UI and the documentation json. Note that you still need to run a server to browse the documentation, but this is very simple:
python -m SimpleHTTPServer
http://localhost:8000/jsondoc-ui.html
If you want the documentation to be totally browsable offline and without a server hosting the ui page, then there is another step to be done, i.e. adding another maven plugin to the flow described previously.
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>1.5.3</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<includes>
<include>${project.build.directory}/jsondoc-ui/jsondoc-ui.html</include>
</includes>
<token>'_JSONDOC_OFFLINE_PLACEHOLDER_'</token> <!-- Do not change this value! -->
<valueFile>${project.build.directory}/jsondoc-ui/jsondoc.json</valueFile>
</configuration>
</plugin>
And then run the mvn clean package -Pdistributable
command again. In the packaged zip you will now find the resulting documentation, browsable offline. Just open the jsondoc-ui.html
page and the documentation will be displayed in your browser.
Here is the resulting piece of the pom file to correctly bundle the documentation in an offline package:
<plugin>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-maven-plugin</artifactId>
<executions>
<execution>
<id>generate-jsondoc</id>
<phase>package</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<version>4.1</version>
<basePath>http://localhost:8080/api</basePath>
<packages>
<package>org.jsondoc.sample.controller</package>
<package>org.jsondoc.sample.pojo</package>
<package>com.sample</package>
</packages>
<outputFile>${project.build.directory}/jsondoc-ui/jsondoc.json</outputFile>
<scanner>org.jsondoc.springmvc.scanner.SpringJSONDocScanner</scanner>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>2.9</version>
<executions>
<execution>
<id>unpack</id>
<phase>process-resources</phase>
<goals>
<goal>unpack</goal>
</goals>
<configuration>
<artifactItems>
<artifactItem>
<groupId>org.jsondoc</groupId>
<artifactId>jsondoc-ui</artifactId>
<type>jar</type>
<overWrite>true</overWrite>
<outputDirectory>${project.build.directory}/jsondoc-ui</outputDirectory>
</artifactItem>
</artifactItems>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.google.code.maven-replacer-plugin</groupId>
<artifactId>replacer</artifactId>
<version>1.5.3</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>replace</goal>
</goals>
</execution>
</executions>
<configuration>
<includes>
<include>${project.build.directory}/jsondoc-ui/jsondoc-ui.html</include>
</includes>
<token>'_JSONDOC_OFFLINE_PLACEHOLDER_'</token> <!-- Do not change this value! -->
<valueFile>${project.build.directory}/jsondoc-ui/jsondoc.json</valueFile>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-assembly-plugin</artifactId>
<executions>
<execution>
<id>create-distribution</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
<configuration>
<finalName>jsondoc</finalName>
<descriptors>
<descriptor>assembly/jsondoc-assembly.xml</descriptor>
</descriptors>
</configuration>
</execution>
</executions>
</plugin>