Merge pull request #149 from aguibert/openapi

Add MP OpenAPI for web-based REST API ui

README.md

@@ -40,6 +40,7 @@ To stop all liberty servers, issue the command:
   - Config (auth-service, game-service, player-service)
   - JWT (auth-service, game-service, player-service)
   - [Rest Client](#microprofile-rest-client) (game-service)
+  - [OpenAPI](#microprofile-openapi) (auth-service, game-service, player-service)
 - Angular 6 (frontend)
 - Gradle build
   - [Liberty Gradle Plugin](#liberty-gradle-plugin)
@@ -149,6 +150,14 @@ liberty {
 }
 ```
 
+## Microprofile OpenAPI
+
+Especially while developing new Rest APIs locally, it is useful to inspect the exposed APIs and test them out manually. Simply by enabling the `mpOpenAPI-1.0` feature in server.xml (no application changes needed), all JAX-RS endpoints will be exposed in an interactive web UI.
+
+Here is a snapshot of what the player-service view looks like:
+
+![Image of MP OpenAPI web ui](https://user-images.githubusercontent.com/5427967/47033512-a87ef100-d13a-11e8-827d-375e0f1c4cae.png)
+
 ## EE Concurrency
 
 Executors from Java SE are very easy to use, and the "Managed" equivalent Executors in EE Concurrency lets you use all of the SE functionality with the added benefit of running the work on threads that are A) managed by the application server and B) have the proper thread context metadata to perform "EE type" operations such as CDI injections and JNDI lookups.

auth-service/build.gradle

@@ -1,7 +1,7 @@
 ext {
 	httpPort = 8082
 	httpsPort = 8482
-	appUrl = "http://localhost:${httpPort}/${war.baseName}" 
+	appUrl = "http://localhost:${httpPort}/openapi/ui"
 }
 
 liberty {
@@ -19,14 +19,3 @@ dependencies {
     compile group: 'com.google.api-client', name: 'google-api-client', version: '1.23.0'
     compile group: 'org.twitter4j', name: 'twitter4j-core', version: '4.0.+'
 }
-
-
-libertyStart.doLast {
-	println "Application available at: ${appUrl}"
-}
-
-task open {
-    doLast {
-        java.awt.Desktop.desktop.browse "${appUrl}/token".toURI()
-    }
-}

auth-service/src/main/java/org/libertybikes/auth/service/github/GitHubOAuthAPI.java

@@ -8,6 +8,7 @@ import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.MediaType;
 
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
 
 @RegisterRestClient
@@ -15,14 +16,13 @@ import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
 public interface GitHubOAuthAPI {
 
     public static class GithubTokenResponse {
-        @NotNull
         public String access_token;
     }
 
     @GET
     @Path("/access_token")
     @Produces(MediaType.APPLICATION_JSON)
-    @Valid // TODO: beanval isn't being honored here when used with MP Rest client
+    @Operation(hidden = true) // hide operation from OpenAPI
     public GithubTokenResponse accessToken(@QueryParam("client_id") String key,
                                            @QueryParam("client_secret") String secret,
                                            @QueryParam("code") String code,

auth-service/src/main/java/org/libertybikes/auth/service/github/GitHubUserAPI.java

@@ -8,6 +8,7 @@ import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.MediaType;
 
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
 
 @RegisterRestClient
@@ -15,7 +16,6 @@ import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
 public interface GitHubUserAPI {
 
     public static class EmailData {
-        @Email
         public String email;
         public boolean primary;
     }
@@ -23,7 +23,7 @@ public interface GitHubUserAPI {
     @GET
     @Path("/emails")
     @Produces(MediaType.APPLICATION_JSON)
-    @Valid // TODO: beanval isn't being called here when rest client instance is injected
+    @Operation(hidden = true) // hide operation from OpenAPI    
     public EmailData[] getEmail(@QueryParam("access_token") String accessToken);
 
 }

auth-service/src/main/liberty/config/server.xml

@@ -9,6 +9,7 @@
         <feature>mpConfig-1.2</feature>
         <feature>mpJwt-1.0</feature>
         <feature>mpRestClient-1.0</feature>
+        <feature>mpOpenAPI-1.0</feature>
     </featureManager>
 
     <httpEndpoint id="defaultHttpEndpoint" host="*" httpPort="${httpPort}" httpsPort="${httpsPort}" />

build.gradle

@@ -67,4 +67,14 @@ subprojects {
     task debug { dependsOn 'libertyDebug' }
     task start { dependsOn 'libertyStart' }
     task stop  { dependsOn 'libertyStop'  }
+    
+    libertyStart.doLast {
+        println "Application available at: ${appUrl}"
+    }
+    
+    task open {
+        doLast {
+            java.awt.Desktop.desktop.browse "${appUrl}".toURI()
+        }
+    }
 }

frontend/build.gradle

@@ -19,6 +19,7 @@ ext {
 	httpPort = 12000
 	httpsPort = 12005
 	applicationName = "${war.archiveName}"
+	appUrl = "http://localhost:${httpPort}/"
 }
 
 war {
@@ -85,13 +86,3 @@ liberty {
 		configDirectory = file('src/main/liberty/config')
 	}
 }
-
-libertyStart.doLast {
-	println "Application available at: http://localhost:${httpPort}/"
-}
-
-task open {
-    doLast {
-        java.awt.Desktop.desktop.browse "http://localhost:${httpPort}/".toURI()
-    }
-}

game-service/build.gradle

@@ -6,6 +6,7 @@ dependencies {
 ext {
 	httpPort = 8080
 	httpsPort = 8443
+	appUrl = "http://localhost:${httpPort}/openapi/ui"
 }
 
 liberty {
@@ -18,8 +19,3 @@ liberty {
 		              '-DsingleParty=' + System.getProperty('singleParty', 'false')]
 	}
 }
-
-
-libertyStart.doLast {
-	println "Application available at: http://localhost:${httpPort}/"
-}

game-service/src/main/java/org/libertybikes/restclient/PlayerService.java

@@ -10,6 +10,7 @@ import javax.ws.rs.Produces;
 import javax.ws.rs.QueryParam;
 import javax.ws.rs.core.MediaType;
 
+import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;
 
 @Dependent
@@ -20,10 +21,12 @@ public interface PlayerService {
     @GET
     @Path("/player/{playerId}")
     @Produces(MediaType.APPLICATION_JSON)
+    @Operation(hidden = true) // hide operation from OpenAPI
     public Player getPlayerById(@PathParam("playerId") String id);
 
     @POST
     @Path("/rank/{playerId}/recordGame")
+    @Operation(hidden = true) // hide operation from OpenAPI
     public void recordGame(@PathParam("playerId") String id, @QueryParam("place") int place, @HeaderParam("Authorization") String token);
 
 }

game-service/src/main/liberty/config/server.xml

@@ -9,6 +9,7 @@
         <feature>mpConfig-1.2</feature>
         <feature>mpRestClient-1.0</feature>
         <feature>mpJwt-1.0</feature>
+        <feature>mpOpenAPI-1.0</feature>
         <feature>websocket-1.1</feature>
     </featureManager>
 

player-service/build.gradle

@@ -1,6 +1,7 @@
 ext {
 	httpPort = 8081
 	httpsPort = 8444
+	appUrl = "http://localhost:${httpPort}/openapi/ui"
 }
 
 liberty {
@@ -12,15 +13,6 @@ liberty {
 	}
 }
 
-libertyStart.doLast {
-	println "Application available at: http://localhost:${httpPort}/${project.name}"
-}
 dependencies {
     compile group: 'io.jsonwebtoken', name: 'jjwt', version: '0.9.0'
 }
-
-task open {
-    doLast {
-        java.awt.Desktop.desktop.browse "http://localhost:${httpPort}/${project.name}".toURI()
-    }
-}

player-service/src/main/liberty/config/server.xml

@@ -8,6 +8,7 @@
         <feature>jsonb-1.0</feature>
         <feature>mpConfig-1.2</feature>
         <feature>mpJwt-1.0</feature>
+        <feature>mpOpenAPI-1.0</feature>
     </featureManager>
 
     <applicationManager autoExpand="true"/>