-
Notifications
You must be signed in to change notification settings - Fork 7
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #80 from Clever/js-client-generation
js client generation
- Loading branch information
Showing
62 changed files
with
2,281 additions
and
95 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -29,4 +29,6 @@ bin/ | |
|
|
||
| vendor/ | ||
| badcode.txt | ||
| release/ | ||
| .DS_Store | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -108,44 +108,64 @@ if err != nil { | |
|
|
||
| If you're using the client from another WAG-ified service you should pass in the `ctx` object you get in your server handler. Otherwise you can use `context.Background()` | ||
|
|
||
| ### Using the Javascript Client from a Node + Express server | ||
| ### Using the Javascript Client | ||
| You can initialize the client by either passing a url or by using [discovery](https://github.com/Clever/discovery-node). | ||
|
|
||
| The Javascript client is generated by a fork of [swagger-codegen](https://github.com/clever/swagger-codegen) that adds support for tracing and retries. | ||
| It has currently only been tested in Node + Express servers. | ||
| ```javascript | ||
| import * as SampleClientLib from 'sample-client-lib-js'; | ||
|
|
||
| The first step is initializing the object named `ApiClient`, and setting the URL of where its located: | ||
| const sampleClient = new SampleClientLib({address: "https://url_of_your_service:port"}); // Explicit url | ||
| // OR | ||
| const sampleClient = new SampleClientLib({discovery: true}); // Using discovery | ||
| ``` | ||
|
|
||
| ```javascript | ||
| import * as yourservice from 'yourservice-js'; | ||
| You may also configure a global timeout for requests when initalizing the client. | ||
|
|
||
| const apiClient = new yourservice.ApiClient(); | ||
| apiClient.basePath = "https://url_of_your_service:port"; | ||
| ```javascript | ||
| const sampleClient = new SampleClientLib({discovery: true, timeout: 1000}); // Timeout any requests taking longer than 1 second | ||
| ``` | ||
|
|
||
| In a request handler, you can use the `apiClient` object as an argument to construct and call specific APIs. | ||
| These specific API objects will be named after the first `tag` you give the operation in your swagger spec. | ||
| You may then call methods on the client. Methods support callbacks and promises. | ||
|
|
||
| ```javascript | ||
| // Promises | ||
| sampleClient.getBookById("bookID").then((book) => { | ||
| // ... | ||
| }).catch((err) => { | ||
| // ... | ||
| }); | ||
|
|
||
| // Callbacks | ||
| sampleClient.getBookById("bookID", (err, book) => { | ||
| // ... | ||
| }); | ||
| ``` | ||
|
|
||
| For example, if you have an operation tagged `Infra` with an `operationId` of `healthCheck`, you would call it like this: | ||
| You can also pass an optional options argument. This can have the following options | ||
| - `timeout` - overide the global timeout for this specific call | ||
| - `span` - Pass an opentracing span to instrument with the call - More on this below | ||
|
|
||
| ```javascript | ||
| app.get('/some_route', (req, res) => { | ||
| const infraAPI = new yourservice.InfraApi(apiClient, {req}); // you must pass the request context through to the client call | ||
| infraAPI.healthCheck().then(function(data) { | ||
| res.send('service called successfully!'); | ||
| }, function(error) { | ||
| console.error(error); | ||
| }); | ||
| const options = { | ||
| timeout: 5000 // Timeout after 5 seconds | ||
| } | ||
|
|
||
| sampleClient.getBookById("bookID", options, (err, book) => { | ||
| // ... | ||
| }); | ||
| ``` | ||
|
|
||
| Additionally, for the above to work you will need to set up server middleware to place tracing-related metadata on the `req` object. | ||
| We currently are testing out LightStep, a service that collects tracing data and displays it in a nice UI: | ||
| #### Tracing | ||
|
|
||
| To utilize the `span` option above you need to pass an opentracing span into the request. The below | ||
| example shows you how to setup an express app to track requests and any calls made via a wag client. | ||
|
|
||
| ```bash | ||
| npm install lightstep-tracer [email protected] --save # >=0.12 contains untested breaking changes to the API | ||
| ``` | ||
|
|
||
| ```javascript | ||
| import * as SampleClientLib from 'sample-client-lib-js'; | ||
| import * as express from 'express'; | ||
| import * as Tracer from 'opentracing'; | ||
| import * as LightStep from 'lightstep-tracer'; | ||
|
|
@@ -155,6 +175,8 @@ Tracer.initGlobalTracer(LightStep.tracer({ | |
| component_name : 'repo-name', | ||
| })); | ||
|
|
||
| const sampleClient = new SampleClientLib({discovery: true}); // Using discovery | ||
|
|
||
| const app = express(); | ||
|
|
||
| // Middleware to look for a span from inbound requests | ||
|
|
@@ -177,6 +199,13 @@ app.use((req, res, next) => { | |
|
|
||
| next(); | ||
| }); | ||
|
|
||
| app.get("/my-url", (req, res) => { | ||
| sampleClient.getBookById("bookID", {span: req.span}, (err, book) => { | ||
| // ... | ||
| }); | ||
| }); | ||
|
|
||
| ``` | ||
|
|
||
| ### Custom String Validation | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| 0.1.0 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,4 @@ | ||
| package client | ||
| package goclient | ||
|
|
||
| import ( | ||
| "bytes" | ||
|
|
||
Oops, something went wrong.