Merge branch 'feature/spring-rest-docs' into develop

README.md

@@ -55,7 +55,7 @@ The project contains unit and integration test examples for standard components
 The project illustrates the use of Spring Boot Actuator for application monitoring and management.  The application demonstrates the recording of custom metrics and the creation of custom health checks.  Also, custom Maven and Gradle project attributes are incorporated into the Actuator info endpoint.
 
 #### API Documentation Generator
-The project includes [Springfox](http://springfox.github.io/springfox/) Swagger integration to automatically generate API docs for the RESTful web service endpoints.  This feature may be activated using the *"docs"* Spring profile.
+The project includes [Spring REST Docs](https://spring.io/projects/spring-restdocs) integration to automatically generate API docs for the RESTful web service endpoints.  This feature may be activated using the *"asciidoctor"* Gradle task.
 
 #### Executable Jar
 The Maven and Gradle builds produce a fully executable Spring Boot Jar file. The Jar file may be executed directly from the command line without the *"java -jar"* command and may be installed on servers as a Linux service.
@@ -279,6 +279,26 @@ java -jar build/libs/example-1.0.0.jar --spring.profiles.active=mysql,batch
 ./example-1.0.0.jar --spring.profiles.active=mysql,batch
 ```
 
+#### asciidoctor
+
+The `asciidoctor` Gradle task performs the following workflow steps:
+
+* compiles Java classes to the /build directory
+* copies all resources to the /build directory
+* executes the unit test suites
+* generates [Asciidoctor](https://asciidoctor.org/) snippets in the /build/generated-snippets directory
+* generates HTML API Docs in the /build/asciidoc/html5 directory
+
+The `asciidoctor` Gradle task generates API documentation using [Spring REST Docs](https://spring.io/projects/spring-restdocs).
+
+To execute the `asciidoctor` Gradle task, type the following command at a terminal prompt in the project base directory.
+
+```
+./gradlew clean asciidoctor
+```
+
+The API documentation is placed in the /build/asciidoc/html5 directory and the root document is named `index.html`.
+
 #### encodePassword
 
 The `encodePassword` Gradle task executes the `BCryptPasswordEncoderUtil` utility class to encode password values which may be included in the sample database scripts.  The clear text password values are passed as a Gradle `-P` property arguments on the command line.

build.gradle

@@ -1,5 +1,6 @@
 plugins {
   id 'org.springframework.boot' version '2.1.1.RELEASE'
+  id 'org.asciidoctor.convert' version '1.5.3'
 }
 
 apply plugin: 'io.spring.dependency-management'
@@ -12,10 +13,11 @@ apply plugin: 'project-report'
 apply plugin: 'build-dashboard'
 
 ext {
+  snippetsDir = file('build/generated-snippets')
+
   jacocoVersion = '0.8.2'
   checkstyleVersion = '8.14'
   pmdVersion = '6.9.0'
-  swaggerVersion = '2.7.0'
 }
 
 group = 'com.leanstacks'
@@ -37,14 +39,16 @@ dependencies {
 
   compile group: 'com.github.ben-manes.caffeine', name: 'caffeine'
   compile group: 'org.liquibase', name: 'liquibase-core'
-  compile group: 'io.springfox', name: 'springfox-swagger2', version: swaggerVersion
-  compile group: 'io.springfox', name: 'springfox-swagger-ui', version: swaggerVersion
 
   runtime group: 'org.hsqldb', name: 'hsqldb'
   runtime group: 'mysql', name: 'mysql-connector-java'
 
   testCompile group: 'org.springframework.boot', name: 'spring-boot-starter-test'
   testCompile group: 'org.springframework.security', name: 'spring-security-test'
+  testCompile group: 'org.springframework.restdocs', name: 'spring-restdocs-mockmvc'
+  testCompile group: 'com.google.guava', name: 'guava', version: '27.0.1-jre'
+
+  asciidoctor group: 'org.springframework.restdocs', name: 'spring-restdocs-asciidoctor'
 }
 
 defaultTasks 'clean', 'build'
@@ -81,7 +85,15 @@ jacocoTestReport {
   }
 }
 
-test.finalizedBy jacocoTestReport
+test {
+  outputs.dir snippetsDir
+  finalizedBy jacocoTestReport
+}
+
+asciidoctor {
+  inputs.dir snippetsDir
+  dependsOn test
+}
 
 checkstyle {
   toolVersion = checkstyleVersion

etc/pmd/ruleset.xml

@@ -51,6 +51,12 @@
 		<exclude name="LoosePackageCoupling" />
 	</rule>
 
+	<rule ref="category/java/design.xml/SignatureDeclareThrowsException">
+		<properties>
+			<property name="IgnoreJUnitCompletely" value="true" />
+		</properties>
+	</rule>
+
 	<rule ref="category/java/documentation.xml" />
 
 	<rule ref="category/java/documentation.xml/CommentSize">

pom.xml

@@ -18,7 +18,6 @@
   <properties>
     <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
     <java.version>11</java.version>
-    <swagger.version>2.7.0</swagger.version>
   </properties>
 
   <dependencies>
@@ -66,18 +65,6 @@
 
     <!-- Dependencies for Miscellaneous Functionality -->
 
-    <!-- Dependencies for Swagger -->
-    <dependency>
-      <groupId>io.springfox</groupId>
-      <artifactId>springfox-swagger2</artifactId>
-      <version>${swagger.version}</version>
-    </dependency>
-    <dependency>
-      <groupId>io.springfox</groupId>
-      <artifactId>springfox-swagger-ui</artifactId>
-      <version>${swagger.version}</version>
-    </dependency>
-
     <!-- Dependencies for Unit Testing -->
     <dependency>
       <groupId>org.springframework.boot</groupId>
@@ -89,6 +76,18 @@
       <artifactId>spring-security-test</artifactId>
       <scope>test</scope>
     </dependency>
+    <dependency>
+      <groupId>com.google.guava</groupId>
+      <artifactId>guava</artifactId>
+      <version>27.0.1-jre</version>
+      <scope>test</scope>
+    </dependency>
+
+    <!-- Dependencies for API Docs -->
+    <dependency>
+    	<groupId>org.springframework.restdocs</groupId>
+    	<artifactId>spring-restdocs-mockmvc</artifactId>
+    </dependency>
   </dependencies>
 
   <build>

src/docs/asciidoc/_includes/http-response-error.adoc

@@ -0,0 +1,16 @@
+[source,http,options="nowrap"]
+----
+HTTP/1.1 404
+Content-Length: 213
+Content-Type: application/json;charset=UTF-8
+
+{
+  "timestamp": "2018-12-12T13:16:11.771539Z",
+  "method": "GET",
+  "path": "/api/...",
+  "status": 404,
+  "statusText": "Not Found",
+  "exceptionClass": "java.util.NoSuchElementException",
+  "exceptionMessage": "No value present"
+}
+----

src/docs/asciidoc/_includes/response-fields-error.adoc

@@ -0,0 +1,32 @@
+|===
+|Path|Type|Description
+
+|`+timestamp+`
+|`+String+`
+|The time the error occurred.
+
+|`+method+`
+|`+String+`
+|The HTTP method.
+
+|`+path+`
+|`+String+`
+|The request context path.
+
+|`+status+`
+|`+Number+`
+|The response HTTP status code.
+
+|`+statusText+`
+|`+String+`
+|The response HTTP status text.
+
+|`+exceptionClass+`
+|`+String+`
+|The exception class.
+
+|`+exceptionMessage+`
+|`+String+`
+|The exception message.
+
+|===

src/docs/asciidoc/create-greeting.adoc

@@ -0,0 +1,40 @@
+= API Endpoint - Create Greeting
+LeanStacks;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:includedir: _includes
+
+== Create a new greeting
+
+=== POST /api/greetings
+
+Create a new greeting.
+
+=== Request Body Parameters
+
+include::{snippets}/create-greeting/request-fields.adoc[]
+
+=== Response Body Parameters
+
+include::{snippets}/create-greeting/response-fields.adoc[]
+
+=== Example Request
+
+Using cURL:
+
+include::{snippets}/create-greeting/curl-request.adoc[]
+
+The HTTP request:
+
+include::{snippets}/create-greeting/http-request.adoc[]
+
+=== Example Response
+
+include::{snippets}/create-greeting/http-response.adoc[]
+
+=== Example Error Response
+
+include::{includedir}/http-response-error.adoc[]
+
+include::{includedir}/response-fields-error.adoc[]

src/docs/asciidoc/delete-greeting.adoc

@@ -0,0 +1,32 @@
+= API Endpoint - Delete Greeting
+LeanStacks;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:includedir: _includes
+
+== Delete a greeting
+
+=== DELETE /api/greetings/{id}
+
+Delete all information about a specific greeting.
+
+=== Example Request
+
+Using cURL:
+
+include::{snippets}/delete-greeting/curl-request.adoc[]
+
+The HTTP request:
+
+include::{snippets}/delete-greeting/http-request.adoc[]
+
+=== Example Response
+
+include::{snippets}/delete-greeting/http-response.adoc[]
+
+=== Example Error Response
+
+include::{includedir}/http-response-error.adoc[]
+
+include::{includedir}/response-fields-error.adoc[]

src/docs/asciidoc/get-greeting.adoc

@@ -0,0 +1,40 @@
+= API Endpoint - Get Greeting
+LeanStacks;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:includedir: _includes
+
+== Get a specific greeting
+
+=== GET /api/greetings/{id}
+
+Get the information about a specific greeting.
+
+=== Path Parameters
+
+include::{snippets}/get-greeting/path-parameters.adoc[]
+
+=== Response Body Parameters
+
+include::{snippets}/get-greeting/response-fields.adoc[]
+
+=== Example Request
+
+Using cURL:
+
+include::{snippets}/get-greeting/curl-request.adoc[]
+
+The HTTP request:
+
+include::{snippets}/get-greeting/http-request.adoc[]
+
+=== Example Response
+
+include::{snippets}/get-greeting/http-response.adoc[]
+
+=== Example Error Response
+
+include::{includedir}/http-response-error.adoc[]
+
+include::{includedir}/response-fields-error.adoc[]

src/docs/asciidoc/get-greetings.adoc

@@ -0,0 +1,36 @@
+= API Endpoint - Get Greetings
+LeanStacks;
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+:includedir: _includes
+
+== Get a list of greetings
+
+=== GET /api/greetings
+
+Get a list of all greetings.
+
+=== Response Body Parameters
+
+include::{snippets}/get-greeting/response-fields.adoc[]
+
+=== Example Request
+
+Using cURL:
+
+include::{snippets}/get-greetings/curl-request.adoc[]
+
+The HTTP request:
+
+include::{snippets}/get-greetings/http-request.adoc[]
+
+=== Example Response
+
+include::{snippets}/get-greetings/http-response.adoc[]
+
+=== Example Error Response
+
+include::{includedir}/http-response-error.adoc[]
+
+include::{includedir}/response-fields-error.adoc[]

src/docs/asciidoc/index.adoc

@@ -0,0 +1,27 @@
+= Overview
+:doctype: book
+:icons: font
+:source-highlighter: highlightjs
+
+Review the available resources from the LeanStacks API. Click any endpoint for additional information.
+
+=== Greetings
+
+[cols="2,4,4",options="header"]
+|===
+
+| HTTP method | Endpoint | Function 
+
+| GET | <<get-greetings.adoc#,/api/greetings>> | Get a list of greetings
+
+| GET | <<get-greeting.adoc#,/api/greetings/{id}>> | Get a specific greeting 
+
+| POST | <<create-greeting.adoc#,/api/greetings>> | Create a greeting 
+
+| PUT | <<update-greeting.adoc#,/api/greetings/{id}>> | Update a greeting 
+
+| DELETE | <<delete-greeting.adoc#,/api/greetings/{id}>> | Delete a greeting 
+
+| POST | <<send-greeting.adoc#,/api/greetings/{id}/send>> | Send a greeting 
+
+|===