Skip to content
Permalink
Browse files

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.
  • Loading branch information...
michael-simons committed Nov 5, 2015
1 parent 837deea commit 56f7868a7c04a93990675546f24f43f62f0aa5aa
@@ -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
66 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>
@@ -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[]
@@ -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@
@@ -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>
@@ -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>

@@ -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>

0 comments on commit 56f7868

Please sign in to comment.
You can’t perform that action at this time.