Spring/spring-restdocs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Make things less Gradle-specific and provide Maven config in samples

Browse Source 
Previously, the project provided a Gradle plugin and was only really
intended for use with Gradle. This had influenced a number of design
choices that have proven to be less than ideal when attempting to
use the project with Maven.

This commit backs off from a number of design decisions that worked
well with Gradle but less so with Maven. Part of this is that the
Gradle plugin is (temporarily?) no more. It's been removed in favour
of configuring things directly in build.gradle. While this slightly
increases the amount of configuration required it makes things far
more flexible.

Both samples have been updated with modified Gradle configuration and
new Maven configuration. The README has also been updated to reflect
these changes.
This commit is contained in:
Andy Wilkinson
2015-01-08 16:51:47 +00:00
parent f67b74304c
commit 6ec522069a
26 changed files with 467 additions and 561 deletions
Download Patch File Download Diff File Expand all files Collapse all files

222
README.md
View File

@@ -1,11 +1,10 @@
## Goal
The primary goal of the project is to make it easy to document RESTful services by
combining content that's been hand-written using [AsciiDoctor][1] with auto-generated
examples produced with the [Spring MVC Test][2] framework. The result is intended to
be an easy-to-read user guide, akin to [GitHub's API documentation][3] for example,
rather than the fully automated, dense API documentation produced by tools like
[Swagger][4].
combining content that's been hand-written with auto-generated examples produced
with the [Spring MVC Test][2] framework. The result is intended to be an easy-to-read
user guide, akin to [GitHub's API documentation][3] for example, rather than the fully
automated, dense API documentation produced by tools like [Swagger][4].
For a broader introduction see the [Documenting RESTful APIs][9] presentation.
@@ -18,59 +17,171 @@ $ ./gradlew build install
```
Once the main project's built, take a look at one of the two sample projects. Both
projects implement a RESTful service for creating tagged notes but have different
implementations: `rest-notes-spring-hateoas` is implemented using Spring MVC and Spring
Hateoas while `rest-notes-spring-data-rest` is implemented using Spring Data REST.
To see the sample project's documentation move into its directory and use Gradle to
build the documentation. For example:
```
$ cd rest-notes-spring-data-rest
$ ./gradlew restDocumentation
```
Once the build is complete, open one of the following:
- build/asciidoc/getting-started-guide.html
- build/asciidoc/api-guide.html
projects implement a RESTful service for creating tagged notes and illustrate the use
of Maven or Gradle. The two projects have different implementations:
`rest-notes-spring-hateoas` is implemented using Spring MVC and Spring Hateoas where as
`rest-notes-spring-data-rest` is implemented using Spring Data REST.
Every example request and response in the documentation is auto-generated using custom
Spring MVC Test result handlers. This ensures that the examples match the service that
they are documenting.
## How does it work
### Building a sample with Gradle
To see the sample project's documentation, move into its directory and use Gradle to
build it. For example:
```
$ cd rest-notes-spring-data-rest
$ ./gradlew asciidoctor
```
Once the build is complete, open one of the following:
- build/asciidoc/html5/getting-started-guide.html
- build/asciidoc/html5/api-guide.html
### Building a sample with Maven
To see the sample project's documentation, move into its directory and use Maven to build
it. For example:
```
$ cd rest-notes-spring-hateoas
$ mvn package
```
Once the build is complete, open one of the following:
- target/generated-docs/getting-started-guide.html
- target/generated-docs/api-guide.html
## How it works
There are three main pieces involved in using this project to document your RESTful
service.
### Gradle plugin
### Build configuration
A Gradle plugin is provided. This plugin builds on top of the [AsciiDoctor plugin][5]
and is responsible for producing the documentation during the build. Assuming you've
built and installed the project as described in the quick start, the plugin as
configured in your project as follows:
Both Maven and Gradle are supported.
#### Gradle configuration
You can look at either samples' `build.gradle` file to see the required configuration.
The key parts are described below.
Configure the AsciiDoctor plugin:
```groovy
buildscript {
repositories {
mavenLocal()
jcenter()
}
dependencies {
classpath 'org.springframework.restdocs:spring-restdocs-gradle-plugin:0.1.0.BUILD-SNAPSHOT'
}
plugins {
id "org.asciidoctor.convert" version "1.5.2"
}
```
Add a dependency on `spring-restdocs-core` in the `testCompile` configuration:
```groovy
dependencies {
testCompile 'org.springframework.restdocs:spring-restdocs-core:0.1.0.BUILD-SNAPSHOT'
}
```
Configure a property to control the location of the generated snippets:
```groovy
ext {
generatedDocumentation = file('build/generated-snippets')
}
```
Configure the `test` task with a system property to control the location to which the
snippets are generated:
test {
systemProperty 'org.springframework.restdocs.outputDir', generatedDocumentation
outputs.dir generatedDocumentation
}
apply plugin: 'org.springframework.restdocs'
Configure the `asciidoctor` task. The `generated` attribute is used to provide easy
access to the generated snippets:
```groovy
asciidoctor {
attributes 'generated': generatedDocumentation
inputs.dir generatedDocumentation
dependsOn test
}
```
#### Maven configuration
You can look at either samples' `pom.xml` file to see the required configuration. The key
parts are described below:
Add a dependency on `spring-restdocs-core` in the `test` scope:
```xml
<dependency>
<groupId>org.springframework.restdocs</groupId>
<artifactId>spring-restdocs-core</artifactId>
<version>0.1.0.BUILD-SNAPSHOT</version>
<scope>test</scope>
</dependency>
```
Configure the SureFire plugin with a system property to control the location to which
the snippets are generated:
```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<includes>
<include>**/*Documentation.java</include>
</includes>
<systemPropertyVariables>
<org.springframework.restdocs.outputDir>${project.build.directory}/generated-snippets</org.springframework.restdocs.outputDir>
</systemPropertyVariables>
</configuration>
</plugin>
```
Configure the AsciiDoctor plugin. The `generated` attribute is used to provide easy
access to the generated snippets:
```xml
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.2</version>
<executions>
<execution>
<id>generate-docs</id>
<phase>package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<doctype>book</doctype>
<attributes>
<generated>${project.build.directory}/generated-snippets</generated>
</attributes>
</configuration>
</execution>
</executions>
</plugin>
```
### Programatically generated snippets
Spring's MVC Test framework is used to make requests to the service that you are
documenting. Any such request wrapped in a call to `RestDocumentation.document` will
produce individual documentation snippets for its request and its response as well as
a snippet that contains both its request and its response.
documenting. A custom `ResultHandler` is used to produce individual documentation
snippets for its request and its response as well as a snippet that contains both its
request and its response.
You can configure the scheme, host, and port of any URIs that appear in the
documentation snippets:
@@ -105,31 +216,50 @@ public void getIndex() {
The code above will perform a `GET` request against the index (`/`) of the service with
an accept header indicating that a JSON response is required. It will write the cURL
command for the request and the resulting response to files in a directory named
`index` in the project's `build/generated-documentation/` directory. Three files will
`index` in the project's `build/generated-snippets/` directory. Three files will
be written:
- `index/request.asciidoc`
- `index/response.asciidoc`
- `index/request-response.asciidoc`
### Documentation written in Asciidoc
### Hand-written documentation
Producing high-quality, easily readable documentation is difficult and the process is
only made harder by trying to write the documentation in an ill-suited format such as
Java annotations. This project addresses this by allowing you to write the bulk of
your documentation's text as an Asciidoc document. These files should be placed in
`src/documentation/asciidoc`.
your documentation's text using [Asciidoctor][1]. The default location for source files
depends on whether you're using Maven or Gradle. By default, AsciiDoctor's Maven plugin
looks in `src/main/asciidoc`, whereas the AsciiDoctor Gradle plugin looks in
`src/docs/asciidoc`
To include the programmatically generated snippets in your documentation, you use
Asciidoc's [`include` macro][6]. The Gradle plugin provides an attribute, `generated`,
that you can use to reference the directory to which the snippets are written. For
example, to include both the request and response snippets described above:
Asciidoc's [`include` macro][6]. The Maven and Gradle configuration described above
configures an attribute, `generated`, that you can use to reference the directory to
which the snippets are written. For example, to include both the request and response
snippets described above:
```
include::{generated}/index/request.asciidoc[]
include::{generated}/index/response.asciidoc[]
```
## Generating snippets in your IDE
As described above, a system property is used to configure the location to which the
generated snippets are written. When running documentation tests in your IDE this system
property will not have been set. If the property is not set the snippets will be written
to standard out.
If you'd prefer that your IDE writes the snippets to disk you can use a file
in `src/test/resources` named `documentation.properties` to configure the property.
For example:
```properties
org.springframework.restdocs.outputDir: target/generated-snippets
```
## Learning more
To learn more, take a look at the accompanying sample projects: