Merge pull request #7 from pilhuhn/rdg

Annotation processor for Swagger annotations.

build-tools/pom.xml

@@ -0,0 +1,54 @@
+<!--
+  ~ Copyright 2015 Red Hat, Inc. and/or its affiliates
+  ~ and other contributors as indicated by the @author tags.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+<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>org.hawkular</groupId>
+  <artifactId>hawkular-build-tools</artifactId>
+  <version>7-SNAPSHOT</version>
+
+  <parent>
+    <groupId>org.hawkular</groupId>
+    <artifactId>hawkular-build-tools-parent</artifactId>
+    <version>7-SNAPSHOT</version>
+    <relativePath>../pom.xml</relativePath>
+  </parent>
+
+  <name>Hawkular Build Tools</name>
+  <description>Contains the Checkstyle configuration for Hawkular projects</description>
+
+  <dependencies>
+    <dependency>
+       <groupId>com.puppycrawl.tools</groupId>
+       <artifactId>checkstyle</artifactId>
+       <version>${version.com.puppycrawl.tools.checkstyle}</version>
+    </dependency>
+
+    <!-- license header checking deps -->
+    <dependency>
+       <groupId>com.mycila</groupId>
+       <artifactId>license-maven-plugin</artifactId>
+       <version>${version.com.mycila.license-maven-plugin}</version>
+    </dependency>
+    <dependency>
+      <groupId>org.eclipse.jgit</groupId>
+      <artifactId>org.eclipse.jgit</artifactId>
+      <version>${version.org.eclipse.jgit}</version>
+    </dependency>
+
+  </dependencies>
+</project>

pom.xml

@@ -22,11 +22,12 @@
   <modelVersion>4.0.0</modelVersion>
 
   <groupId>org.hawkular</groupId>
-  <artifactId>hawkular-build-tools</artifactId>
+  <artifactId>hawkular-build-tools-parent</artifactId>
   <version>7-SNAPSHOT</version>
+  <packaging>pom</packaging>
 
-  <name>Hawkular Build Tools</name>
-  <description>Contains the Checkstyle configuration for Hawkular projects</description>
+  <name>Hawkular Build Tools Parent</name>
+  <description>Contains build tools for Hawkular projects</description>
   <url>https://github.com/hawkular/hawkular-build-tools</url>
   <organization>
     <name>Red Hat, Inc.</name>
@@ -90,24 +91,11 @@
     <version.junit>4.12</version.junit>
   </properties>
 
+  <modules>
+    <module>build-tools</module>
+    <module>rest-docs-generator</module>
+  </modules>
   <dependencies>
-    <dependency>
-       <groupId>com.puppycrawl.tools</groupId>
-       <artifactId>checkstyle</artifactId>
-       <version>${version.com.puppycrawl.tools.checkstyle}</version>
-    </dependency>
-
-    <!-- license header checking deps -->
-    <dependency>
-       <groupId>com.mycila</groupId>
-       <artifactId>license-maven-plugin</artifactId>
-       <version>${version.com.mycila.license-maven-plugin}</version>
-    </dependency>
-    <dependency>
-      <groupId>org.eclipse.jgit</groupId>
-      <artifactId>org.eclipse.jgit</artifactId>
-      <version>${version.org.eclipse.jgit}</version>
-    </dependency>
 
     <!-- test scope stuff -->
     <dependency>

rest-docs-generator/README.adoc

@@ -0,0 +1,65 @@
+= REST-docs-generator
+:icons: font
+
+This package contains an annotation processor that looks at the Swagger and JAX-RS annotations and generates
+documentation in AsciiDoc format and/or a generic XML output, that can be further transformed via XSLT.
+
+
+
+== Simple setup
+
+To use the processor without any additional configuration, it is enough to add the following dependency on your maven
+ project:
+
+[source,xml,indent=0]
+----
+    <dependency>
+      <groupId>org.hawkular.apt</groupId>
+      <artifactId>rest-docs-generator</artifactId>
+      <version>1.0.0</version>  <!--1-->
+      <scope>provided</scope>
+    </dependency>
+----
+<1> You may check for the latest version
+
+Maven compiler plugin will see this and add it to the Java compiler classpath, which in turn will through
+the embedded service provider file enable the processor.
+
+== Parametrized setup
+
+In many cases the above simple setup is enough. If you want or need to parametrize the processor, you can
+do that via configuring the maven-processor-plugin like this:
+
+[source,xml,indent=0]
+----
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <configuration>
+          <annotationProcessors>
+            <annotationProcessor>org.hawkular.apt.restdocs.Processor</annotationProcessor>
+          </annotationProcessors>
+          <compilerArguments>
+            <AtargetDirectory>${project.build.directory}/docs/</AtargetDirectory> <!--1-->
+            <AmodelPkg>org.rhq.helpers.rest_docs_generator.test</AmodelPkg>   <!--2-->
+            <Averbose>false</Averbose>  <!--3-->
+            <AskipPkg/> <!--4-->
+            <AoutputFormat>xml,adoc</AoutputFormat> <!--5-->
+            <AheaderLine>Rest-Api for Hawkular rest processor</AheaderLine> <!--6-->
+            <AabortPattern>_$logger</AabortPattern> <!--7-->
+          </compilerArguments>
+        </configuration>
+      </plugin>
+----
+<1> Target direction for the generated documentation files. Default is `target/docs`.
+<2> Package in which the Api / DTO classes are. Used to shorten Fully Qualified Names.
+<3> Should be processor be noisy?
+<4> Skip processing of classes in this java package
+<5> What output formats should be written? Currently supported is adoc
+<6> A header line for the file header
+<7> A pattern for `String.contains()` that if found in class names aborts the processing. This can be used in
+situations where another processor is writing data to a `generated-sources` directory, that will be processed
+separately after the first round. Without skipping, the processing of the `generated-sources` would overwrite the
+data from the first run that did all the annotation processing already.
+
+
+Of course you still need above dependency section even with the parametrized setup.

rest-docs-generator/pom.xml

@@ -0,0 +1,99 @@
+<!--
+  ~ Copyright 2015 Red Hat, Inc. and/or its affiliates
+  ~ and other contributors as indicated by the @author tags.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+<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>org.hawkular.apt</groupId>
+  <artifactId>rest-docs-generator</artifactId>
+  <version>1.0.0</version>
+  <packaging>jar</packaging>
+
+  <properties>
+    <maven.compiler.source>1.7</maven.compiler.source>
+    <maven.compiler.target>1.7</maven.compiler.target>
+  </properties>
+
+
+  <dependencies>
+    <dependency>
+      <groupId>com.wordnik</groupId>
+      <artifactId>swagger-annotations_2.10.0</artifactId>
+      <version>1.2.5</version>
+      <scope>compile</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.jboss.resteasy</groupId>
+      <artifactId>resteasy-jaxrs</artifactId>
+      <version>3.0.10.Final</version>
+      <scope>compile</scope>
+    </dependency>
+    <dependency>
+      <groupId>javax.ws.rs</groupId>
+      <artifactId>jsr311-api</artifactId>
+      <version>1.1.1</version>
+      <scope>compile</scope>
+    </dependency>
+    <dependency>
+      <groupId>javax.ejb</groupId>
+      <artifactId>ejb-api</artifactId>
+      <version>3.0</version>
+      <scope>compile</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.2</version>
+        <configuration>
+          <!-- disable processing for the default compile, as we would need the processor for it -->
+          <proc>none</proc>
+        </configuration>
+        <executions>
+          <execution>
+            <!-- Execute the compiled plugin on the test sources -->
+            <id>create-rest-api-reports</id>
+            <phase>process-test-classes</phase>
+            <goals>
+              <!-- We want to process the classes in test/ -->
+              <goal>testCompile</goal>
+            </goals>
+            <configuration>
+              <annotationProcessors>
+                <processor>org.hawkular.apt.restdocs.Processor</processor>
+              </annotationProcessors>
+              <proc>only</proc>
+              <compilerArguments>
+                <AtargetDirectory>${project.build.directory}/docs</AtargetDirectory>
+                <AmodelPkg>org.hawkular.apt.restdocs.test</AmodelPkg>
+                <!-- enable the next line to have the output of the processor shown on console -->
+                <!--<Averbose>true</Averbose>-->
+                <AoutputFormat>adoc,xml</AoutputFormat>
+              </compilerArguments>
+            </configuration>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+
+</project>