Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Usage

neil-laurance edited this page · 30 revisions
Clone this wiki locally

Annotations

The following Spring 3 REST annotations are supported:

@Controller Annotates a RESTful service class
@RequestMapping Annotates a RESTful service endpoint (URI and request method: GET, PUT, POST, DELETE)
@ResponseBody Annotates a RESTful service response type. Concrete types preferred over abstract interfaces
@PathVariable Annotates a (mandatory) URI path variable
@RequestParam Annotates a (generally optional) request variable

In addition, RESTdoclet will recognise a custom Javadoc tag @uriDeprecated in the service method comment to selectively mark deprecated URIs

For example,

/**
 * Request mapping for industry.
 *
 * @param industryId    the industry id
 * @param pageNum       page number
 * @param pageSize      page size
 * @param sortField     sort field
 * @param sortDirection sort direction
 * @uriDeprecated {"/deprecated/uri", "/deprecated/uri2"}
 * @return constituents
 */
@RequestMapping(value = {"/industries/{industryId}/constituents","/deprecated/uri", "/deprecated/uri2"}, method = RequestMethod.GET)
@ResponseBody
public ConstituentsPageDto getIndustriesConstituents(
      @PathVariable("industryId") String industryId,
      @RequestParam(value = "page_number", required = false, defaultValue = "1") int pageNum,
      @RequestParam(value = "page_size", required = false, defaultValue = PagingService.NO_PAGE_SIZE_SPECIFIED) int pageSize,
      @RequestParam(value = "sort_field", required = false, defaultValue = "PERCENT") String sortField,
      @RequestParam(value = "sort_direction", required = false, defaultValue = "ASCENDING") String sortDirection) {

   return getConstituents(new IndustryIdPredicate(industryId), pageNum, pageSize, sortField, sortDirection);
}

Download

RESTDoclet may either be downloaded and built from github, or is available in binary form on oss.sonatype.org.

Maven Configuration

Web Project

Add the maven configuration below to your RESTful web project pom.xml.

<profiles>
          <profile>
                 <id>default-profile</id>
                 <activation>
                       <activeByDefault>true</activeByDefault>
                       <file>
                              <exists>${java.home}/../lib/tools.jar</exists>
                       </file>
                 </activation>
                 <properties>
                       <toolsjar>${java.home}/../lib/tools.jar</toolsjar>
                 </properties>
          </profile>
          <profile>
                 <id>mac-profile</id>
                 <activation>
                       <activeByDefault>false</activeByDefault>
                       <file>
                              <exists>${java.home}/../Classes/classes.jar</exists>
                       </file>
                 </activation>
                 <properties>
                       <toolsjar>${java.home}/../Classes/classes.jar</toolsjar>
                 </properties>
        </profile>
	<profile>
		<id>restdoclet</id>
		<build>
			<plugins>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-install-plugin</artifactId>
					<version>2.3.1</version>
					<executions>
						<execution>
							<id>tools-install</id>
							<phase>validate</phase>
							<configuration>
								<file>${toolsjar}</file>
								<repositoryLayout>default</repositoryLayout>
								<groupId>com.sun</groupId>
								<artifactId>tools</artifactId>
								<version>1.4.2</version>
								<packaging>jar</packaging>
								<generatePom>true</generatePom>
							</configuration>
							<goals>
								<goal>install-file</goal>
							</goals>
						</execution>
					</executions>
				</plugin>
				<plugin>
					<artifactId>maven-javadoc-plugin</artifactId>
					<version>2.8</version>
					<configuration>
						<doclet>com.iggroup.oss.restdoclet.doclet.XmlDoclet</doclet>
						<docletArtifact>
							<groupId>com.iggroup.oss.restdoclet</groupId>
							<artifactId>restdoclet-doclet</artifactId>
							<version>2.2.0</version>
						</docletArtifact>
						<useStandardDocletOptions>false</useStandardDocletOptions>
						<includeDependencySources>true</includeDependencySources>
						<dependencySourceIncludes>
							<dependencySourceInclude>com.iggroup.oss.sample*:*</dependencySourceInclude>
						</dependencySourceIncludes>
						<includeTransitiveDependencySources>false</includeTransitiveDependencySources>
						<additionalJOption>-J-DRESTDOCLET_LOGGING=${RESTDOCLET_LOGGING}</additionalJOption>
					</configuration>
					<executions>
						<execution>
							<id>attach-javadocs</id>
							<goals>
								<goal>jar</goal>
							</goals>
						</execution>
						<execution>
							<goals>
								<goal>javadoc</goal>
							</goals>
						</execution>
					</executions>
				</plugin>
				<plugin>
					<groupId>com.iggroup.oss.restdoclet</groupId>
					<artifactId>restdoclet-plugin</artifactId>
					<version>2.2.0</version>
					<configuration>
						<contextRoot>/optionalContextRoot</contextRoot>
						<excludes>
							<exclude>none</exclude>
						</excludes>
					</configuration>
					<executions>
						<execution>
							<goals>
								<goal>restdoclet</goal>
							</goals>
						</execution>
					</executions>
				</plugin>
				<plugin>
					<groupId>org.codehaus.mojo</groupId>
					<artifactId>build-helper-maven-plugin</artifactId>
					<executions>
						<execution>
							<id>attach-artifacts</id>
							<phase>package</phase>
							<goals>
								<goal>attach-artifact</goal>
							</goals>
							<configuration>
								<artifacts>
									<artifact>
										<file>target/${project.build.finalName}-restdoclet.jar</file>
										<type>jar</type>
										<classifier>restdoclet</classifier>
									</artifact>
								</artifacts>
							</configuration>
						</execution>
					</executions>
				</plugin>
				<plugin>
					<groupId>org.apache.maven.plugins</groupId>
					<artifactId>maven-dependency-plugin</artifactId>
					<version>2.4</version>
					<executions>
						<execution>
							<id>unpack war and configuration</id>
							<phase>install</phase>
							<goals>
								<goal>unpack</goal>
							</goals>
							<configuration>
								<artifactItems>
									<artifactItem>
										<groupId>${project.groupId}</groupId>
										<artifactId>${project.artifactId}</artifactId>
										<version>${project.version}</version>
										<type>jar</type>
										<classifier>restdoclet</classifier>
										<overWrite>true</overWrite>
										<outputDirectory>${RESTDOCLET_DEPLOY}/${project.artifactId}
										</outputDirectory>
									</artifactItem>
								</artifactItems>
							</configuration>
						</execution>
					</executions>
				</plugin>

			</plugins>
		</build>
	</profile>
</profiles>

<scm>
	<connection>scm:svn:http://...</connection>
	<developerConnection>scm:svn:http://...</developerConnection>
	<url>http://...</url>
</scm>    

Dependent Projects

If your services reference classes that are not in the web project, then in addition to uncommenting the commented out section in the pom above and configuring one or more base packages to scan, the following configuration will need to be added to the pom of the referenced Java maven project(s):

<profile>
	<id>restdoc</id>
	<build>
		<plugins>
			<plugin>
				<artifactId>maven-source-plugin</artifactId>
				<version>2.1.1</version>
				<executions>
					<execution>
						<id>bundle-sources</id>
						<phase>package</phase>
						<goals>
							<goal>jar</goal>
						</goals>
					</execution>
				</executions>
			</plugin>
		</plugins>
	</build>
</profile>

Maven Execution

RESTdoc is generated as part of the maven package phase and using the restdoc profile, e.g.

set MAVEN_OPTS=-DRESTDOCLET_LOGGING=debug -DRESTDOCLET_DEPLOY=/temp/restdoclet
mvn install -Prestdoclet

Using the configuration above, this command will create a set of XML output files under /temp/restdoclet/${project.artifactId}

Note: when defining RESTDOCLET_DEPLOY, use forward slashes, not backslashes

Note: it is recommended that the MAVEN_OPTS settings above are used as they will help troubleshoot initial configuration of your project.

Deployment

In order to view the generated RESTdoclet in a browser, RESTdoclet includes a web app that renders the generated documentation xml files. This web application will need to be deployed to a web application server such as Tomcat. By default the web application will look for the $RESTDOCLET_DEPLOY environment variable for any generated RESTdoclet configuration XML files. This location may easily be edited in the file applications.jsp.

For convenience, a Tomcat plugin is included in the RESTdoclet web project and executed as follows:

mvn install tomcat:redeploy -Prestdoclet

This will deploy the RESTdoclet web application a standard localhost Tomcat instance (tweak the Indexer pom to change the default settings), and RESTdoclet will be available at http://localhost:8080/restdoclet.

Enjoy!

Something went wrong with that request. Please try again.