Spotify Docgenerator Maven Plugin

Generates Documentation of Jersey services and Jackson annotated data clasess

License

License

Categories

Categories

Maven Build Tools
GroupId

GroupId

com.spotify.docgenerator
ArtifactId

ArtifactId

docgenerator-maven-plugin
Last Version

Last Version

0.0.1
Release Date

Release Date

Type

Type

maven-plugin
Description

Description

Spotify Docgenerator Maven Plugin
Generates Documentation of Jersey services and Jackson annotated data clasess
Project URL

Project URL

http://maven.apache.org

Download docgenerator-maven-plugin

How to add to project

<plugin>
    <groupId>com.spotify.docgenerator</groupId>
    <artifactId>docgenerator-maven-plugin</artifactId>
    <version>0.0.1</version>
</plugin>

Dependencies

compile (14)

Group / Artifact Type Version
javax.inject : javax.inject jar 1
com.fasterxml.jackson.core : jackson-databind jar 2.4.1
com.spotify.docgenerator : common jar 0.0.1
commons-logging : commons-logging jar 1.1.1
com.google.guava : guava jar 17.0
org.apache.maven : maven-plugin-api jar 2.2.1
org.apache.maven.reporting : maven-reporting-api jar 3.0
org.apache.maven.reporting : maven-reporting-impl jar 2.2
org.codehaus.plexus : plexus-utils jar 3.0.8
org.apache.maven.doxia : doxia-core jar 1.2
org.apache.maven.doxia : doxia-sink-api jar 1.2
org.apache.maven.doxia : doxia-decoration-model jar 1.2
org.apache.maven.doxia : doxia-site-renderer jar 1.2
org.apache.maven.shared : maven-doxia-tools jar 1.4

provided (2)

Group / Artifact Type Version
org.apache.maven.plugin-tools : maven-plugin-annotations jar 3.3
com.intellij : annotations jar 12.0

Project Modules

There are no modules declared in this project.

Docgenerator

Generates a maven report named rest.html that contains the javax.ws.rs annotated HTTP endpoint methods and Jackson @JsonProperty annotated objects, and a few other things.

#To Use

Maven Configuration

There are two parts to the documentation generator:

  1. The annotation processor that scans the code for annotations and drops files based upon what it finds
  2. The maven report plugin that takes those things, and possibly jar file locations, and generates the report.

First, to add the annotation processor to your code, add the following bit to the pom.xml of you project.

    <dependency>
      <groupId>com.spotify.docgenerator</groupId>
      <artifactId>scanner</artifactId>
      <version>WHATEVER_THE_LATEST_VERSION_IS</version>
    </dependency>

Then for the actual documentation, if you're not using a reactor project, you'll include something like this:

  <reporting>
    <plugins>
      <plugin>
        <groupId>com.spotify.docgenerator</groupId>
        <artifactId>docgenerator-maven-plugin</artifactId>
        <version>0.0.1</version>
        <configuration>
          <jsonClassesFiles>
            <jsonClassesFile>${project.build.directory}/classes/JSONClasses</jsonClassesFile>
          </jsonClassesFiles>
          <restEndpointsFiles>
            <restEndpointsFile>${project.build.directory}/classes/RESTEndpoints</restEndpointsFile>
          </restEndpointsFiles>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

If you're in a reactor project (such as Helios, from which this project originated), it may look something like this:

  <reporting>
    <plugins>
      <plugin>
        <groupId>com.spotify.docgenerator</groupId>
        <artifactId>docgenerator-maven-plugin</artifactId>
        <version>0.0.1</version>
        <configuration>
          <jsonClassesFiles>
            <jsonClassesFile>${project.build.directory}/../../helios-client/target/classes/JSONClasses</jsonClassesFile>
          </jsonClassesFiles>
          <restEndpointsFiles>
            <restEndpointsFile>${project.build.directory}/../../helios-services/target/classes/RESTEndpoints</restEndpointsFile>
          </restEndpointsFiles>
          <jarFiles>
            <jarFile>${project.build.directory}/../../helios-client/target/helios-client-${project.version}.jar</jarFile>
          </jarFiles>
        </configuration>
      </plugin>
    </plugins>
  </reporting>

Note, if your documentation requires, as the example above, other submodules of your reactor project, make sure to list them as dependencies in the <dependencies> section, so they will be built before the documentation gets built.

The <jarFiles> bits are primarily for the case of enum types. Basically, it's for types referenced by one of the Jackson-serialized classes, that themselves aren't Jackson-serialized.

Building the Docs

To build the docs, it should be a simple matter of running:

mvn package site

After it's done, the docs should be in target/site/rest.html.

#TODO

  • The Javadoc processing is pretty pathetic
  • Someone who has visual design skills could provide very useful improvements.
  • maybe: Alternatively to doing the maven report plugin thing, a separate tool could be written that processed the output files and produced pretty docs.

#Under The Hood The annotation processor will cause two files to be dropped in the target/classes directory when the package is built. They are named JSONClasses which will be serialized form of Map<String, TransferClass> which describes the Jackson annotated classes it found, and the other file is named RESTEndpoints which is the serialized form of List<ResourceMethod> describing the javax.ws.rs methods it found. The serialized classes in question are in the common package.

com.spotify.docgenerator

Spotify

Versions

Version
0.0.1