Add Spring REST Doc to the mix

This update brings Spring REST Doc to the mix: A simple way to bind your API documentation to your Tests. I really like it.
michael-simons · Nov 5, 2015 · 56f7868 · 56f7868
1 parent 837deea
commit 56f7868
Show file tree

Hide file tree

Showing 9 changed files with 500 additions and 103 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,18 @@ This is a project where i try out Java 8, Spring / Spring Boot and AngularJS. Th
 
 You may also want to have a look at the client companion of this app, [BikingFX][4]
 
+## NOTE
+
+You'll need [GPSBabel][5] to build this project without errors and to use the tracks / log database. Errors running the `TracksControllerTest` are the result of a missing `gpsbabel` binary in the path.
+
+Per default, biking2 looks at `/opt/local/bin/gpsbabel` for the GPSBabel binary. This can be overwritten by adding an application.properties to the root of the project containing the following property:
+
+    biking2.gpsBabel = path/to/gpsbabel/binary
+
+GPSBabel is available for all major operating systems, including windows. So please check if it's available on your platform if biking2 doesn't compile for you.
+
 [1]: http://biking.michael-simons.eu
 [2]: http://biking.michael-simons.eu/about
 [3]: http://info.michael-simons.eu/2014/02/20/developing-a-web-application-with-spring-boot-angularjs-and-java-8/
-[4]: https://github.com/michael-simons/bikingFX
+[4]: https://github.com/michael-simons/bikingFX
+[5]: http://www.gpsbabel.org
diff --git a/pom.xml b/pom.xml
@@ -5,12 +5,12 @@
 
     <groupId>eu.michael-simons</groupId>
     <artifactId>biking2</artifactId>
-    <version>1.8.2-SNAPSHOT</version>
+    <version>1.9.3-SNAPSHOT</version>
 
     <parent>
 	<groupId>org.springframework.boot</groupId>
 	<artifactId>spring-boot-starter-parent</artifactId>
-	<version>1.2.6.RELEASE</version>
+	<version>1.2.7.RELEASE</version>
     </parent>
 
     <name>biking2</name>
@@ -57,6 +57,8 @@
 	<maven.compiler.target>${java.version}</maven.compiler.target>
 
 	<start-class>ac.simons.biking2.Application</start-class>	
+
+	<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
     </properties>
 
     <build>
@@ -77,14 +79,56 @@
 		    </compilerArgs>	
 		</configuration>
 	    </plugin>
+	    <plugin> 
+		<groupId>org.asciidoctor</groupId>
+		<artifactId>asciidoctor-maven-plugin</artifactId>
+		<version>1.5.2</version>
+		<executions>
+		    <execution>
+			<id>generate-docs</id>
+			<phase>prepare-package</phase> 
+			<goals>
+			    <goal>process-asciidoc</goal>
+			</goals>
+			<configuration>
+			    <backend>html</backend>
+			    <doctype>book</doctype>
+			    <attributes>
+				<snippets>${snippetsDirectory}</snippets> 
+			    </attributes>
+			</configuration>
+		    </execution>
+		</executions>
+	    </plugin>
 	    <plugin>
 		<groupId>org.apache.maven.plugins</groupId>
-		<artifactId>maven-resources-plugin
-		</artifactId>
+		<artifactId>maven-resources-plugin</artifactId>
+		<version>2.7</version>
 		<configuration>
 		    <encoding>${project.build.sourceEncoding}</encoding>
 		    <overwrite>false</overwrite>
 		</configuration>
+		<executions>
+		    <execution>
+			<id>copy-resources</id>
+			<phase>prepare-package</phase>
+			<goals>
+			    <goal>copy-resources</goal>
+			</goals>
+			<configuration>
+			    <outputDirectory>
+				${project.build.outputDirectory}/static/docs
+			    </outputDirectory>
+			    <resources>
+				<resource>
+				    <directory>
+					${project.build.directory}/generated-docs
+				    </directory>
+				</resource>
+			    </resources>
+			</configuration>
+		    </execution>
+		</executions>
 	    </plugin>
 	    <plugin>
 		<groupId>org.apache.maven.plugins</groupId>
@@ -185,7 +229,7 @@
 			</configuration>
 		    </execution>
 		</executions>
-	    </plugin>
+	    </plugin>	    	    
 	</plugins>
 	<resources>
 	    <resource>
@@ -389,5 +433,17 @@
 	    <version>0.1.3</version>
 	    <scope>test</scope>
 	</dependency>
+	<dependency>
+	    <groupId>org.jooq</groupId>
+	    <artifactId>joor</artifactId>
+	    <version>0.9.5</version>
+	    <scope>test</scope>
+	</dependency>
+	<dependency> 
+	    <groupId>org.springframework.restdocs</groupId>
+	    <artifactId>spring-restdocs-mockmvc</artifactId>	    
+	    <version>1.0.0.RELEASE</version>
+	    <scope>test</scope>
+	</dependency>
     </dependencies>
 </project>
diff --git a/src/main/asciidoc/guide-and-api.adoc b/src/main/asciidoc/guide-and-api.adoc
@@ -0,0 +1,146 @@
+= biking.michael-simons.eu Guide and API
+Michael Simons;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:toc: left
+:toclevels: 3
+:sectlinks:
+
+[[introduction]]
+== Introduction
+
+http://biking.michael-simons.eu[biking.michael-simons.eu] is a project for 
+
+* tracking my bike activities
+* evaluating technology
+* learn stuff
+* showcasing my skills
+
+For my information see http://info.michael-simons.eu/2014/02/20/developing-a-web-application-with-spring-boot-angularjs-and-java-8/[this blog post] as a starting point.
+
+I'd like to thank all the people working at the Spring Eco System for doing their amazing work.
+
+[[api]]
+== Api
+
+[[bikes]]
+=== Bikes
+
+[[listing-bikes]]
+
+==== Listing bikes
+
+A `GET` request will list all of the service's bikes.
+
+===== Request Parameter
+
+include::{snippets}/api/bikes/get/request-parameters.adoc[]
+
+[[bike-structure]]
+===== Response structure
+
+include::{snippets}/api/bikes/get/response-fields.adoc[]
+
+===== Example request
+
+include::{snippets}/api/bikes/get/curl-request.adoc[]
+
+===== Example response
+
+include::{snippets}/api/bikes/get/http-response.adoc[]
+
+==== Creating a bike
+
+A `POST` request is used to create a new bike
+
+===== Request structure
+
+include::{snippets}/api/bikes/post/request-fields.adoc[]
+
+===== Example request
+
+include::{snippets}/api/bikes/post/curl-request.adoc[]
+
+===== Example response
+
+include::{snippets}/api/bikes/post/http-response.adoc[]
+
+==== Adding milages to bikes
+
+A bike manages its total milage at a given date. To make it easy for the user, no difference needs to be calculated, the user can enter the milage of is bike as stated on the odometer or whatever.
+
+A `POST` request will add a new milage to a given bike.
+
+===== Path Parameters
+
+include::{snippets}/api/bikes/milages/post/path-parameters.adoc[]
+
+===== Request structure
+
+include::{snippets}/api/bikes/milages/post/request-fields.adoc[]
+
+===== Example request
+
+include::{snippets}/api/bikes/milages/post/curl-request.adoc[]
+
+===== Example response
+
+include::{snippets}/api/bikes/milages/post/http-response.adoc[]
+
+==== Adding a story to a bike
+
+Bikes can have an associated story, how they were build or whatever.
+
+A `PUT` request will update a given bike with a new story.
+
+===== Path Parameters
+
+include::{snippets}/api/bikes/story/put/path-parameters.adoc[]
+
+===== Request structure
+
+include::{snippets}/api/bikes/story/put/request-fields.adoc[]
+
+===== Example request
+
+include::{snippets}/api/bikes/story/put/curl-request.adoc[]
+
+===== Example response
+
+The reponse is an updated <<bike-structure,bike>>.
+
+include::{snippets}/api/bikes/story/put/http-response.adoc[]
+
+===== Deleting a story
+
+An empty `PUT` request deletes a bikes story:
+
+include::{snippets}/api/bikes/story/put-empty/curl-request.adoc[]
+
+include::{snippets}/api/bikes/story/put-empty/http-response.adoc[]
+
+[[trips]]
+=== Trips
+
+To keep track of all milage including time not spent on persistent bikes, the user can store assorted trips. A trip is a distance covered at a certain date.
+
+==== Creating a trip
+
+A `POST` request is used to create a new trip
+
+===== Request structure
+
+include::{snippets}/api/trips/post/request-fields.adoc[]
+
+===== Example request
+
+include::{snippets}/api/trips/post/curl-request.adoc[]
+
+===== Response structure
+
+include::{snippets}/api/trips/post/response-fields.adoc[]
+
+===== Example response
+
+include::{snippets}/api/trips/post/http-response.adoc[]
diff --git a/src/main/resources/build.properties b/src/main/resources/build.properties
@@ -12,12 +12,12 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-build-date = ${build-date}
+build-date = @build-date@
 
-versions.angularjs = ${angularjs.version}
-versions.app = ${pom.version}
-versions.bootstrap = ${bootstrap.version}
-versions.hibernate = ${hibernate.version}
-versions.highcharts = ${highcharts.version}
-versions.spring = ${spring.version}
-versions.spring-boot = ${spring-boot.version}
+versions.angularjs = @angularjs.version@
+versions.app = @pom.version@
+versions.bootstrap = @bootstrap.version@
+versions.hibernate = @hibernate.version@
+versions.highcharts = @highcharts.version@
+versions.spring = @spring.version@
+versions.spring-boot = @spring-boot.version@
diff --git a/src/main/webapp/public/index.html b/src/main/webapp/public/index.html
@@ -7,20 +7,20 @@
 
 	<link rel="icon" type="image/x-icon" href="/favicon.ico" />
 
-	<link rel="stylesheet" type="text/css" href="/webjars/bootstrap/${bootstrap.version}/css/bootstrap.min.css" />		
+	<link rel="stylesheet" type="text/css" href="/webjars/bootstrap/@bootstrap.version@/css/bootstrap.min.css" />		
 	<link rel="stylesheet" type="text/css" href="/css/stylesheet.css" />
 
-	<script type="text/javascript" src="/webjars/jquery/${jquery.version}/jquery.min.js"></script>
-	<script type="text/javascript" src="/webjars/bootstrap/${bootstrap.version}/js/bootstrap.min.js"></script>
-	<script type="text/javascript" src="/webjars/angular-file-upload/${angular-file-upload.version}/angular-file-upload-html5-shim.min.js"></script>
-	<script type="text/javascript" src="/webjars/angularjs/${angularjs.version}/angular.min.js"></script>
-	<script type="text/javascript" src="/webjars/angularjs/${angularjs.version}/angular-route.min.js"></script>
-	<script type="text/javascript" src="/webjars/angular-file-upload/${angular-file-upload.version}/angular-file-upload.min.js"></script>
-	<script type="text/javascript" src="/webjars/angular-ui-bootstrap/${angular-ui-bootstrap.version}/ui-bootstrap.min.js"></script>
-	<script type="text/javascript" src="/webjars/angular-ui-bootstrap/${angular-ui-bootstrap.version}/ui-bootstrap-tpls.min.js"></script>	
-	<script type="text/javascript" src="/webjars/highcharts/${highcharts.version}/highcharts.js"></script>
-	<script type="text/javascript" src="/webjars/highcharts/${highcharts.version}/highcharts-more.js"></script>
-	<script type="text/javascript" src="/webjars/openlayers/${openlayers.version}/OpenLayers.js"></script>
+	<script type="text/javascript" src="/webjars/jquery/@jquery.version@/jquery.min.js"></script>
+	<script type="text/javascript" src="/webjars/bootstrap/@bootstrap.version@/js/bootstrap.min.js"></script>
+	<script type="text/javascript" src="/webjars/angular-file-upload/@angular-file-upload.version@/angular-file-upload-html5-shim.min.js"></script>
+	<script type="text/javascript" src="/webjars/angularjs/@angularjs.version@/angular.min.js"></script>
+	<script type="text/javascript" src="/webjars/angularjs/@angularjs.version@/angular-route.min.js"></script>
+	<script type="text/javascript" src="/webjars/angular-file-upload/@angular-file-upload.version@/angular-file-upload.min.js"></script>
+	<script type="text/javascript" src="/webjars/angular-ui-bootstrap/@angular-ui-bootstrap.version@/ui-bootstrap.min.js"></script>
+	<script type="text/javascript" src="/webjars/angular-ui-bootstrap/@angular-ui-bootstrap.version@/ui-bootstrap-tpls.min.js"></script>	
+	<script type="text/javascript" src="/webjars/highcharts/@highcharts.version@/highcharts.js"></script>
+	<script type="text/javascript" src="/webjars/highcharts/@highcharts.version@/highcharts-more.js"></script>
+	<script type="text/javascript" src="/webjars/openlayers/@openlayers.version@/OpenLayers.js"></script>
 	<script type="text/javascript" src="http://www.openstreetmap.org/openlayers/OpenStreetMap.js"></script>
 
 	<script src="/js/sockjs.js"></script>

diff --git a/src/main/webapp/public/partials/_about.html b/src/main/webapp/public/partials/_about.html
@@ -6,7 +6,11 @@ <h2>About</h2>
 
 	<p>I've blogged about my goals rewriting the old application from scratch here <a href="http://info.michael-simons.eu/2014/02/20/developing-a-web-application-with-spring-boot-angularjs-and-java-8/">Developing a web application with Spring Boot, AngularJS and Java 8</a>, the source code is available here <a href="https://github.com/michael-simons/biking2">github.com/michael-simons/biking2</a>.</p>
 
-	<p>There's also a little companion app, a JavaFX 8 client obviously called <a href="https://github.com/michael-simons/bikingFX">BikingFX</a> written in October 2014, after JavaOne. If you like, get started with JavaFX 8 right here: <a href="http://info.michael-simons.eu/2014/10/22/getting-started-with-javafx-8-developing-a-rest-client-application-from-scratch/">Developing a JavaFX REST client application from scratch</a>.</p>
+	<p>
+	    There's also a little companion app, a JavaFX 8 client obviously called <a href="https://github.com/michael-simons/bikingFX">BikingFX</a> written in October 2014, after JavaOne. If you like, get started with JavaFX 8 right here: <a href="http://info.michael-simons.eu/2014/10/22/getting-started-with-javafx-8-developing-a-rest-client-application-from-scratch/">Developing a JavaFX REST client application from scratch</a>.
+	    <br />
+	    The api of this service is documented <a target="_self" href="/docs/guide-and-api.html">here</a>. The beautiful documentation is partially generated and then rendered using <a href="http://projects.spring.io/spring-restdocs/">Spring REST Docs</a>, a really clever solution, that ties api documentation to valid tests.
+	</p>
 
 	<p>Until early 2014 this application was <a href="http://www.ruby-lang.org">Ruby</a> and <a href="http://www.sinatrarb.com/">Sinatra</a> based and consisted mainly of one big *.rb file. The blog post about the old application is still online here: <a href="http://info.michael-simons.eu/2009/07/29/creating-a-self-containing-mvc-application-with-sinatra/">Creating a self containing mvc application with Sinatra</a>, together with the old <a target="_self" href="/misc/biking.rb">source code</a>.</p>
 

diff --git a/src/main/webapp/public/partials/_bikes.html b/src/main/webapp/public/partials/_bikes.html
@@ -9,7 +9,7 @@ <h2>Bikes</h2>
 	</p>  
 	<p class="text-muted"><small>(Someone sent me this picture, if its copyrighted, please just let me know and don't sue me.)</small></p>
 	<div class="row">
-	    <div class="col-md-6">
+	    <div class="col-lg-8 col-md-9 col-xs-12 col-sm-12">
 		<p>So here is my fleet:</p>
 		<table class="table table-condensed table-bordered table-striped">
 		    <thead>