Add detailed readme (#5)

README.md

@@ -1,15 +1,124 @@
-conjure-java-example
-===================
-A simple dropwizard backend application that uses conjure bindings. 
+# conjure-java-example
+A small recipe application that demonstrates the simple usage of conjure tooling.
 
-Gradle Tasks
-------------
-`./gradlew tasks` - to get the list of gradle tasks
+## Overview
 
+#### Tools and Libraries
 
-Start Developing
-----------------
-Run one of the following commands:
+This example project uses the following tools and libraries, please consult their respective documentation for more information.
 
+* [conjure](https://github.com/palantir/conjure) - IDL for defining APIs once and generating client/server interfaces in different languages.
+    * [conjure-java-runtime](https://github.com/palantir/http-remoting/) - conjure libraries for HTTP&JSON-based RPC using Retrofit, Feign, OkHttp as clients and Jetty/Jersey as servers
+    * [conjure-java](https://github.com/palantir/conjure-java) - conjure generator for java clients and servers 
+    * [conjure-typescript](https://github.com/palantir/conjure-typescript) - conjure generator for typescript clients
+* [gradle](https://gradle.org/) - a highly flexible build tool. Some of the gradle plugins applied are:
+     *  [gradle-conjure](https://github.com/palantir/gradle-conjure) - a gradle plugin that contains tasks to generate conjure bindings.
+     *  [gradle-baseline](https://github.com/palantir/gradle-baseline) - a gradle plugin for configuring code quality tools in builds and projects.
+* [dropwizard](https://www.dropwizard.io/1.3.5/docs/) - a simple framework for building web services
+
+#### Project Structure
+
+* `recipe-example-api` - a sub-project that defines recipe-example APIs in Conjure and generates both java and typescript bindings.
+
+    This is what the api project looks like:
+    ```
+    ├── recipe-example-api
+    │   ├── build.gradle
+    │   ├── recipe-example-api-jersey
+    │   ├── recipe-example-api-objects
+    │   ├── recipe-example-api-typescript
+    │   └── src
+    │       └── main
+    │           └── conjure
+    │               └── recipe-example-api.yml
+    ```
+    * build.gradle - a gradle script that 
+        1. configures sub-projects with needed dependencies to generate java bindings. e.g. `recipe-example-api-jersey`
+        2. configures `publishTypescript` task to generate `.npmrc` in the generated root folder, `recipe-example-api-typescript/src` for publishing the generated npm module.
+        3. modifies the `conjure` extension to specify the package name under which the npm module will be published.
+    * recipe-example-api-jersey - the sub-project where all generated [service interfaces](https://github.com/palantir/conjure-java-example/blob/0.1.1/example-api/src/main/conjure/example-api.yml#L39) live.
+    * recipe-example-api-objects - the sub-project where all generated [object classes](https://github.com/palantir/conjure-java-example/blob/0.1.1/example-api/src/main/conjure/example-api.yml#L4) live.
+    * recipe-example-api-typescript - the sub-project where all generated typescript bindings live.
+    * src/main/conjure - directory containing conjure definition yml files where recipe APIs are defined, please refer to [specification.md](https://github.com/palantir/conjure/blob/develop/docs/specification.md) for more details.
+
+* `recipe-example-server` - a dropwizard application project that uses conjure generated jersey binding for resource class implementation
+
+    This is what the server project looks like:
+    ```
+    ├── recipe-example-server
+    │   ├── build.gradle
+    │   ├── src
+    │   │   ├── main
+    │   │   │   └── java
+    │   │   │       └── com
+    │   │   │           └── palantir
+    │   │   │               └── conjure
+    │   │   │                   └── examples
+    │   │   │                       ├── RecipeBookApplication.java
+    │   │   │                       ├── RecipeBookConfiguration.java
+    │   │   │                       └── resources
+    │   │   │                           └── RecipeBookResource.java
+    │   │   └── test
+    │   │       ├── java
+    │   │       │   └── com
+    │   │       │       └── palantir
+    │   │       │           └── conjure
+    │   │       │               └── examples
+    │   │       │                   └── RecipeBookApplicationTest.java
+    │   │       └── resources
+    │   │           └── test.yml
+    │   └── var
+    │       └── conf
+    │           └── recipes.yml
+    ```
+    * build.gradle - configures the project with needed dependencies and applies the `gradle-conjure` and `application plugins`, so we can run the server locally or in IDE.
+    * src/main/java - source classes for the dropwizard application. e.g. RecipeBookResource.java class `implements` the generated Jersey interface.
+    * test/main/java - test source classes for simple integration tests that uses generated jersey interface for client interaction.
+    * var/conf/recipes.yml - the dropwizard application configuration yml file
+
+* build.gradle - the root level gradle script where a set of gradle plugins are configured, including [gradle-conjure](https://github.com/palantir/gradle-conjure).
+* settings.gradle - the gradle settings file where all sub projects are configured.
+* versions.props - a property file of the [nebula version recommender plugin](https://github.com/nebula-plugins/nebula-dependency-recommender-plugin) with which we can specify versions of project dependencies, including conjure generators.
+
+## Development
+
+#### Useful Gradle Commands:
+
+* `./gradlew tasks` for tasks available in this project.
 * `./gradlew idea` for IntelliJ
 * `./gradlew eclipse` for Eclipse
+* `./gradlew run` for running the server or use IDE to debug it
+
+#### Generate New or Modify Existing APIs
+
+##### Modify existing APIs
+To modify the existing bindings in this project:
+1. Make changes to the `recipe-example-api/src/main/conjure/recipe-api.yml` file
+2. Run `./gradlew compileConjure` or a more specific task such as `./gradlew compileConjureObjects`, to check if the changes compile
+3. Or run `./gradlew idea` or `./gradlew eclipse` to update the bindings for your IDE
+
+##### Generate new binding for a different language
+To generate bindings for a new language. Note that currently `gradle-conjure` plugin only supports generation of java, typescript, and python bindings.
+1. Add a new sub project under `recipe-example-api` by modifying the `settings.gradle` file. 
+    ```diff
+    ...
+    include 'example-api:example-api-typescript'
+    + include 'example-api:example-api-python'
+    ```
+2. Optional: use the gradle script `configure` closure in `recipe-example-api/build.gradle` to configure project specific settings for the new sub project.
+3. Specify conjure python dependency versions in versions.props
+   ```diff
+   + com.palantir.conjure.python:* = 3.4.0
+   ```
+4. run `./gradlew compileConjure` to generate new bindings for python.
+
+##### Generate Java retrofit interfaces
+Similar to how we add the conjure generation for python above, we can add a new project to generate java retrofit interfaces
+1. add a new sub project under `recipe-example-api` by modifying the `settings.gradle` file. 
+    ```diff
+    ...
+    include 'example-api:example-api-typescript'
+    + include 'recipe-example-api:recipe-example-api-retrofit'
+    ```
+2. Optional: use the gradle script `configure` closure in `recipe-example-api/build.gradle` to configure project specific settings for the new sub project. 
+3. run `./gradlew compileConjureRetrofit` to generate new bindings for python.

build.gradle

@@ -52,7 +52,7 @@ allprojects {
     }
 }
 
-configure(subprojects - project(':example-api')) {
+configure(subprojects - project(':recipe-example-api')) {
     apply plugin: 'java'
     apply plugin: 'com.palantir.baseline-checkstyle'
     apply plugin: 'com.palantir.baseline-eclipse'

example-api/build.gradle → recipe-example-api/build.gradle

@@ -16,15 +16,14 @@
 
 apply plugin: 'com.palantir.conjure'
 
-configure(subprojects - project('example-api-typescript')) {
+configure(subprojects - project('recipe-example-api-typescript')) {
     dependencies {
         compile 'com.palantir.conjure.java:conjure-lib'
         compile 'com.fasterxml.jackson.core:jackson-databind'
     }
-    tasks.compileJava.dependsOn compileConjure
 }
 
-project (':example-api:example-api-typescript') {
+project (':recipe-example-api:recipe-example-api-typescript') {
     publishTypeScript.doFirst {
         file('src/.npmrc') << "//registry.npmjs.org/:_authToken=${System.env.NPM_AUTH_TOKEN}"
     }
@@ -33,6 +32,6 @@ project (':example-api:example-api-typescript') {
 // optional, only needed if you want to override the default settings
 conjure {
     typescript {
-        packageName = "conjure-examples-api" // default package name is the project name, `example-api`
+        packageName = "conjure-recipe-example-api" // default package name is the project name, `recipe-example-api`
     }
 }

example-api/src/main/conjure/example-api.yml → recipe-example-api/src/main/conjure/recipe-example-api.yml

@@ -1,6 +1,6 @@
 types:
   definitions:
-    default-package: com.palantir.conjure.examples.recipes.api
+    default-package: com.palantir.conjure.examples.recipe.api
     objects:
       Temperature:
         fields:
@@ -39,21 +39,21 @@ types:
 services:
   RecipeBookService:
     name: Recipe Book
-    package: com.palantir.conjure.examples.recipes.api
-    base-path: /
+    package: com.palantir.conjure.examples.recipe.api
+    base-path: /recipes
     docs: |
       APIs for retrieving recipes
 
     endpoints:
       createRecipe:
-        http: POST /recipes
+        http: POST /
         args:
           createRecipeRequest:
             param-type: body
             type: Recipe
 
       getRecipe:
-        http: GET /recipes/{name}
+        http: GET /{name}
         args:
           name: RecipeName
         returns: Recipe
@@ -64,10 +64,10 @@ services:
                  The name of the recipe
 
       getAllRecipes:
-        http: GET /recipes
+        http: GET /
         returns: set<Recipe>
 
       deleteRecipe:
-        http: DELETE /recipes/{name}
+        http: DELETE /{name}
         args:
           name: RecipeName

example-server/build.gradle → recipe-example-server/build.gradle

@@ -3,8 +3,8 @@ apply plugin: 'application'
 dependencies {
     processor 'org.immutables:value'
 
-    compile project(':example-api:example-api-objects')
-    compile project(':example-api:example-api-jersey')
+    compile project(':recipe-example-api:recipe-example-api-objects')
+    compile project(':recipe-example-api:recipe-example-api-jersey')
 
     compile 'com.google.guava:guava'
     compile 'com.palantir.remoting3:jackson-support'

example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java → recipe-example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java

@@ -17,7 +17,7 @@
 package com.palantir.conjure.examples;
 
 import com.fasterxml.jackson.annotation.JsonProperty;
-import com.palantir.conjure.examples.recipes.api.Recipe;
+import com.palantir.conjure.examples.recipe.api.Recipe;
 import com.palantir.websecurity.WebSecurityConfigurable;
 import com.palantir.websecurity.WebSecurityConfiguration;
 import io.dropwizard.Configuration;

example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java → recipe-example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java

@@ -17,10 +17,10 @@
 package com.palantir.conjure.examples.resources;
 
 import com.google.common.base.Preconditions;
-import com.palantir.conjure.examples.recipes.api.Recipe;
-import com.palantir.conjure.examples.recipes.api.RecipeBookService;
-import com.palantir.conjure.examples.recipes.api.RecipeErrors;
-import com.palantir.conjure.examples.recipes.api.RecipeName;
+import com.palantir.conjure.examples.recipe.api.Recipe;
+import com.palantir.conjure.examples.recipe.api.RecipeBookService;
+import com.palantir.conjure.examples.recipe.api.RecipeErrors;
+import com.palantir.conjure.examples.recipe.api.RecipeName;
 import java.util.HashSet;
 import java.util.Map;
 import java.util.Set;

example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java → recipe-example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java

@@ -20,9 +20,9 @@
 import static org.junit.Assert.assertEquals;
 
 import com.google.common.io.Resources;
-import com.palantir.conjure.examples.recipes.api.Recipe;
-import com.palantir.conjure.examples.recipes.api.RecipeBookService;
-import com.palantir.conjure.examples.recipes.api.RecipeName;
+import com.palantir.conjure.examples.recipe.api.Recipe;
+import com.palantir.conjure.examples.recipe.api.RecipeBookService;
+import com.palantir.conjure.examples.recipe.api.RecipeName;
 import feign.Client;
 import feign.Feign;
 import feign.FeignException;

settings.gradle

@@ -1,7 +1,7 @@
 rootProject.name = 'conjure-java-example'
 
-include 'example-server'
-include 'example-api'
-include 'example-api:example-api-objects'
-include 'example-api:example-api-jersey'
-include 'example-api:example-api-typescript'
+include 'recipe-example-server'
+include 'recipe-example-api'
+include 'recipe-example-api:recipe-example-api-objects'
+include 'recipe-example-api:recipe-example-api-jersey'
+include 'recipe-example-api:recipe-example-api-typescript'