JarCasting
JarCasting JarCasting

Restdoc Maven Plugin

Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/

Categories

Categories

Maven Build Tools
GroupId

GroupId

org.commonjava.maven
ArtifactId

ArtifactId

restdoc-maven-plugin
Last Version

Last Version

0.1
Release Date

Release Date
Type

Type

maven-plugin
Description

Description

Restdoc Maven Plugin
Sonatype helps open source projects to set up Maven repositories on https://oss.sonatype.org/
Source Code Management

Source Code Management

http://github.com/jdcasey/restdoc-maven-plugin

Download restdoc-maven-plugin

Filename Size
restdoc-maven-plugin-0.1.pom
restdoc-maven-plugin-0.1.jar 17 KB
restdoc-maven-plugin-0.1-sources.jar 8 KB
restdoc-maven-plugin-0.1-javadoc.jar 40 KB
Browse

How to add to project

<plugin>
    <groupId>org.commonjava.maven</groupId>
    <artifactId>restdoc-maven-plugin</artifactId>
    <version>0.1</version>
</plugin>

Dependencies

compile (3)

Group / Artifact Type Version
org.apache.maven : maven-plugin-api jar 3.0.3
org.codehaus.plexus : plexus-utils jar 3.0.8
org.apache.maven : maven-core jar 3.0.3

provided (1)

Group / Artifact Type Version
org.apache.maven.plugin-tools : maven-plugin-annotations jar 3.2

test (1)

Group / Artifact Type Version
junit : junit jar 4.8.2

Project Modules

There are no modules declared in this project.

Restdoc Maven Plugin

This plugin aggregates and transforms XML metadata gleaned from annotation processing with org.rhq.helper:rest-docs-generator, which uses annotations from the JAX-RS spec and from the swagger project to generate documentation about REST endpoints and datatypes. By default, it generates HTML output using a built-in stylesheet that was originally from here.

Currently, this is A VERY RUDIMENTARY IMPLEMENTATION. The best I can currently say about the generated HTML is that it's better than nothing. Marginally. However, the aggregated XML offers more promise, especially when coupled with a jQuery-driven UI.

Build.

Building is simple: mvn clean install

Use.

In your project's top-level POM, add this:

<dependencies>
  <dependency>
    <groupId>com.wordnik</groupId>
    <artifactId>swagger-annotations_2.9.1</artifactId>
    <version>1.2.3</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>org.rhq.helpers</groupId>
    <artifactId>rest-docs-generator</artifactId>
    <version>4.6.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>
[...]
<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.1</version>
        <executions>
          <execution>
            <id>generate-restdoc</id>
            <phase>generate-resources</phase>
            <goals>
              <goal>compile</goal>
            </goals>
            <configuration>
              <annotationProcessors>
                <processor>org.rhq.helpers.rest_docs_generator.ClassLevelProcessor</processor>
              </annotationProcessors>
              <proc>only</proc>
              <compilerArguments>
                <AtargetDirectory>${project.build.directory}/classes/META-INF/rest-docs</AtargetDirectory>
                <AmodelPkg>org.commonjava.aprox.model</AmodelPkg>
                <!-- <AskipPkg>org.rhq.enterprise.server.rest.reporting</AskipPkg> -->
                <!-- enable the next line to have the output of the processor shown on console -->
                <Averbose>true</Averbose>
              </compilerArguments>
              <!-- set the next to true to enable verbose output of the compiler plugin; default from the evn is true, but this is too noisy -->
              <verbose>false</verbose>
            </configuration>
          </execution>
        </executions>
      </plugin>
      <plugin>
        <groupId>org.commonjava.maven</groupId>
        <artifactId>restdoc-maven-plugin</artifactId>
        <version>0.1-SNAPSHOT</version>
        <executions>
          <execution>
            <id>generate-html</id>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </pluginManagement>
</build>

This will automatically attempt to process any classes in your project tree that have JAX-RS or Swagger annotations. Next, in your WAR module, add:

<build>
  <pluginManagement>
    <plugins>
      <plugin>
        <artifactId>maven-war-plugin</artifactId>
        <configuration>
          <webResources>
            <webResource>
              <directory>${project.build.directory}/restdocs</directory>
            </webResource>
          </webResources>
        </configuration>
      </plugin>
    </plugins>
  </pluginManagement>
  <plugins>
    <plugin>
      <groupId>org.commonjava.maven</groupId>
      <artifactId>restdoc-maven-plugin</artifactId>
    </plugin>
  </plugins>
</build>

When your build runs, your WAR should contain two new documents:

/restdocs.html
/restdocs.xml

The first is aggregated and transformed using the HTML XSLT stylesheet. The second is simply aggregated output from the annotation processor, which may be used from javascript or other UIs.

Other Options.

Check mvn org.commonjava.maven:restdoc-maven-plugin:0.1-SNAPSHOT:help for more usage information.

Versions

Version
0.1