JSONDoc

easily generate docs and playground for your RESTful API

Contacts

Email StackOverflow

How to: package docs bundle

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:

Declare the 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>

Unpack the 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>

Repackage into a distributable zip

<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>

Browsing the documentation using a webserver

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:

  • Unzip the package in a directory of your choiche
  • Move to that directory and in a terminal just type python -m SimpleHTTPServer
  • Open the browser and browse the documentation at http://localhost:8000/jsondoc-ui.html

Browsing the documentation without using a webserver

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.

Example pom for offline bundle generation

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>

Version 1.2.23 | Licensed under MIT License

GitHub Project | Issues