From eea1d18f97faf1bf51a4b0ea1a7874b662bb6c66 Mon Sep 17 00:00:00 2001 From: Qinfeng Chen Date: Wed, 25 Jul 2018 18:08:32 +0100 Subject: [PATCH] Add detailed readme (#5) --- .bulldozer.yml | 3 - README.md | 127 ++++++++++++++++-- build.gradle | 2 +- .../build.gradle | 7 +- .../recipe-example-api-jersey}/.gitignore | 0 .../recipe-example-api-objects}/.gitignore | 0 .../recipe-example-api-typescript}/.gitignore | 0 .../src/main/conjure/recipe-example-api.yml | 14 +- .../build.gradle | 4 +- .../examples/RecipeBookApplication.java | 0 .../examples/RecipeBookConfiguration.java | 2 +- .../resources/RecipeBookResource.java | 8 +- .../examples/RecipeBookApplicationTest.java | 6 +- .../src/test/resources/test.yml | 0 .../var/conf/recipes.yml | 0 settings.gradle | 10 +- 16 files changed, 144 insertions(+), 39 deletions(-) delete mode 100644 .bulldozer.yml rename {example-api => recipe-example-api}/build.gradle (80%) rename {example-api/example-api-jersey => recipe-example-api/recipe-example-api-jersey}/.gitignore (100%) rename {example-api/example-api-objects => recipe-example-api/recipe-example-api-objects}/.gitignore (100%) rename {example-api/example-api-typescript => recipe-example-api/recipe-example-api-typescript}/.gitignore (100%) rename example-api/src/main/conjure/example-api.yml => recipe-example-api/src/main/conjure/recipe-example-api.yml (82%) rename {example-server => recipe-example-server}/build.gradle (83%) rename {example-server => recipe-example-server}/src/main/java/com/palantir/conjure/examples/RecipeBookApplication.java (100%) rename {example-server => recipe-example-server}/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java (96%) rename {example-server => recipe-example-server}/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java (88%) rename {example-server => recipe-example-server}/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java (93%) rename {example-server => recipe-example-server}/src/test/resources/test.yml (100%) rename {example-server => recipe-example-server}/var/conf/recipes.yml (100%) diff --git a/.bulldozer.yml b/.bulldozer.yml deleted file mode 100644 index ee629100..00000000 --- a/.bulldozer.yml +++ /dev/null @@ -1,3 +0,0 @@ -mode: whitelist -strategy: squash -deleteAfterMerge: true diff --git a/README.md b/README.md index 8c7d3e00..364be076 100644 --- a/README.md +++ b/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. diff --git a/build.gradle b/build.gradle index f261677f..4958a33b 100644 --- a/build.gradle +++ b/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' diff --git a/example-api/build.gradle b/recipe-example-api/build.gradle similarity index 80% rename from example-api/build.gradle rename to recipe-example-api/build.gradle index 8face318..f838538f 100644 --- a/example-api/build.gradle +++ b/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` } } diff --git a/example-api/example-api-jersey/.gitignore b/recipe-example-api/recipe-example-api-jersey/.gitignore similarity index 100% rename from example-api/example-api-jersey/.gitignore rename to recipe-example-api/recipe-example-api-jersey/.gitignore diff --git a/example-api/example-api-objects/.gitignore b/recipe-example-api/recipe-example-api-objects/.gitignore similarity index 100% rename from example-api/example-api-objects/.gitignore rename to recipe-example-api/recipe-example-api-objects/.gitignore diff --git a/example-api/example-api-typescript/.gitignore b/recipe-example-api/recipe-example-api-typescript/.gitignore similarity index 100% rename from example-api/example-api-typescript/.gitignore rename to recipe-example-api/recipe-example-api-typescript/.gitignore diff --git a/example-api/src/main/conjure/example-api.yml b/recipe-example-api/src/main/conjure/recipe-example-api.yml similarity index 82% rename from example-api/src/main/conjure/example-api.yml rename to recipe-example-api/src/main/conjure/recipe-example-api.yml index b3e43254..58d7109e 100644 --- a/example-api/src/main/conjure/example-api.yml +++ b/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 deleteRecipe: - http: DELETE /recipes/{name} + http: DELETE /{name} args: name: RecipeName diff --git a/example-server/build.gradle b/recipe-example-server/build.gradle similarity index 83% rename from example-server/build.gradle rename to recipe-example-server/build.gradle index 6df21c26..1ee18507 100644 --- a/example-server/build.gradle +++ b/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' diff --git a/example-server/src/main/java/com/palantir/conjure/examples/RecipeBookApplication.java b/recipe-example-server/src/main/java/com/palantir/conjure/examples/RecipeBookApplication.java similarity index 100% rename from example-server/src/main/java/com/palantir/conjure/examples/RecipeBookApplication.java rename to recipe-example-server/src/main/java/com/palantir/conjure/examples/RecipeBookApplication.java diff --git a/example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java b/recipe-example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java similarity index 96% rename from example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java rename to recipe-example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java index 65f1b49a..7da13291 100644 --- a/example-server/src/main/java/com/palantir/conjure/examples/RecipeBookConfiguration.java +++ b/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; diff --git a/example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java b/recipe-example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java similarity index 88% rename from example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java rename to recipe-example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java index b6528310..1cfb0adf 100644 --- a/example-server/src/main/java/com/palantir/conjure/examples/resources/RecipeBookResource.java +++ b/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; diff --git a/example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java b/recipe-example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java similarity index 93% rename from example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java rename to recipe-example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java index edf001ee..10bf63e6 100644 --- a/example-server/src/test/java/com/palantir/conjure/examples/RecipeBookApplicationTest.java +++ b/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; diff --git a/example-server/src/test/resources/test.yml b/recipe-example-server/src/test/resources/test.yml similarity index 100% rename from example-server/src/test/resources/test.yml rename to recipe-example-server/src/test/resources/test.yml diff --git a/example-server/var/conf/recipes.yml b/recipe-example-server/var/conf/recipes.yml similarity index 100% rename from example-server/var/conf/recipes.yml rename to recipe-example-server/var/conf/recipes.yml diff --git a/settings.gradle b/settings.gradle index da5f3bdf..d9d0ad7c 100644 --- a/settings.gradle +++ b/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'