From 3a39d3e73cc31dd3a666e7a771cb41d5c1f585fb Mon Sep 17 00:00:00 2001 From: Will Plusnick Date: Wed, 13 Nov 2019 09:39:36 -0600 Subject: [PATCH] Add documentation and examples for new open api spec support --- Godeps/Godeps.json | 112 +++++++++-- ..._hello_world_apigateway_open_api_spec.yaml | 28 +++ docs/examples/open_api_spec.json | 60 ++++++ docs/wskdeploy_apigateway_open_api_spec.md | 177 ++++++++++++++++++ 4 files changed, 364 insertions(+), 13 deletions(-) create mode 100644 docs/examples/manifest_hello_world_apigateway_open_api_spec.yaml create mode 100644 docs/examples/open_api_spec.json create mode 100644 docs/wskdeploy_apigateway_open_api_spec.md diff --git a/Godeps/Godeps.json b/Godeps/Godeps.json index eeaede534..1b463cb7a 100644 --- a/Godeps/Godeps.json +++ b/Godeps/Godeps.json @@ -1,16 +1,8 @@ { "ImportPath": "github.com/apache/openwhisk-wskdeploy", "GoVersion": "go1.9", - "GodepVersion": "v80", + "GodepVersion": "v62", "Deps": [ - { - "ImportPath": "github.com/apache/openwhisk-client-go/whisk", - "Rev": "ee5b8709787cd37201c42e38040e9709f6d1e9c8" - }, - { - "ImportPath": "github.com/apache/openwhisk-client-go/wski18n", - "Rev": "ee5b8709787cd37201c42e38040e9709f6d1e9c8" - }, { "ImportPath": "github.com/cloudfoundry/jibber_jabber", "Rev": "bcc4c8345a21301bf47c032ff42dd1aae2fe3027" @@ -21,14 +13,50 @@ "Rev": "570b54cabe6b8eb0bc2dfce68d964677d63b5260" }, { - "ImportPath": "github.com/ghodss/yaml", - "Comment": "v1.0.0-14-g25d852a", - "Rev": "25d852aebe32c875e9c044af3eef9c7dc6bc777f" + "ImportPath": "github.com/fsnotify/fsnotify", + "Comment": "v1.4.2-2-gfd9ec7d", + "Rev": "fd9ec7deca8bf46ecd2a795baaacf2b3a9be1197" }, { "ImportPath": "github.com/google/go-querystring/query", "Rev": "9235644dd9e52eeae6fa48efd539fdc351a0af53" }, + { + "ImportPath": "github.com/hashicorp/hcl", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/hcl/ast", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/hcl/parser", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/hcl/scanner", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/hcl/strconv", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/hcl/token", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/json/parser", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/json/scanner", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, + { + "ImportPath": "github.com/hashicorp/hcl/json/token", + "Rev": "973f376f0e7cf09c96e445b44712416c0cb22ec4" + }, { "ImportPath": "github.com/hokaccha/go-prettyjson", "Rev": "f75235bd99dad4e98ff360db8372d5c0ef1d054a" @@ -37,6 +65,11 @@ "ImportPath": "github.com/inconshreveable/mousetrap", "Rev": "76626ae9c91c4f2a10f34cad8ce83ea42c93bb75" }, + { + "ImportPath": "github.com/magiconair/properties", + "Comment": "v1.7.0-5-g0723e35", + "Rev": "0723e352fa358f9322c938cc2dadda874e9151a9" + }, { "ImportPath": "github.com/mattn/go-colorable", "Comment": "v0.0.6-9-gd228849", @@ -46,6 +79,10 @@ "ImportPath": "github.com/mattn/go-isatty", "Rev": "66b8e73f3f5cda9f96b69efd03dd3d7fc4a5cdb8" }, + { + "ImportPath": "github.com/mitchellh/mapstructure", + "Rev": "f3009df150dadf309fdee4a54ed65c124afad715" + }, { "ImportPath": "github.com/nicksnyder/go-i18n/i18n", "Comment": "v1.6.0-1-g991e81c", @@ -66,21 +103,70 @@ "Comment": "v1.6.0-1-g991e81c", "Rev": "991e81cc94f6c54209edb3192cb98e3995ad71c1" }, + { + "ImportPath": "github.com/apache/openwhisk-client-go/whisk", + "Rev": "ee5b8709787cd37201c42e38040e9709f6d1e9c8" + }, + { + "ImportPath": "github.com/apache/openwhisk-client-go/wski18n", + "Rev": "ee5b8709787cd37201c42e38040e9709f6d1e9c8" + }, + { + "ImportPath": "github.com/pelletier/go-buffruneio", + "Rev": "df1e16fde7fc330a0ca68167c23bf7ed6ac31d6d" + }, + { + "ImportPath": "github.com/pelletier/go-toml", + "Comment": "v0.3.5-16-g45932ad", + "Rev": "45932ad32dfdd20826f5671da37a5f3ce9f26a8d" + }, + { + "ImportPath": "github.com/spf13/afero", + "Rev": "06b7e5f50606ecd49148a01a6008942d9b669217" + }, + { + "ImportPath": "github.com/spf13/afero/mem", + "Rev": "06b7e5f50606ecd49148a01a6008942d9b669217" + }, + { + "ImportPath": "github.com/spf13/cast", + "Rev": "2580bc98dc0e62908119e4737030cc2fdfc45e4c" + }, { "ImportPath": "github.com/spf13/cobra", "Rev": "6e91dded25d73176bf7f60b40dd7aa1f0bf9be8d" }, + { + "ImportPath": "github.com/spf13/jwalterweatherman", + "Rev": "33c24e77fb80341fe7130ee7c594256ff08ccc46" + }, { "ImportPath": "github.com/spf13/pflag", "Rev": "5ccb023bc27df288a957c5e994cd44fd19619465" }, + { + "ImportPath": "github.com/spf13/viper", + "Rev": "651d9d916abc3c3d6a91a12549495caba5edffd2" + }, { "ImportPath": "golang.org/x/sys/unix", "Rev": "9a2e24c3733eddc63871eda99f253e2db29bd3b9" }, + { + "ImportPath": "golang.org/x/text/transform", + "Rev": "a8b38433e35b65ba247bb267317037dee1b70cea" + }, + { + "ImportPath": "golang.org/x/text/unicode/norm", + "Rev": "a8b38433e35b65ba247bb267317037dee1b70cea" + }, { "ImportPath": "gopkg.in/yaml.v2", "Rev": "eb3733d160e74a9c7e442f435eb3bea458e1d19f" - } + }, + { + "ImportPath": "github.com/palantir/stacktrace", + "Rev": "78658fd2d1772b755720ed8c44367d11ee5380d6" + } ] } diff --git a/docs/examples/manifest_hello_world_apigateway_open_api_spec.yaml b/docs/examples/manifest_hello_world_apigateway_open_api_spec.yaml new file mode 100644 index 000000000..26826e967 --- /dev/null +++ b/docs/examples/manifest_hello_world_apigateway_open_api_spec.yaml @@ -0,0 +1,28 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +# Example: Basic Hello World action with Open API Specification +project: + config: open_api_spec.json + packages: + hello_world_package: + version: 1.0 + license: Apache-2.0 + actions: + hello_world: + function: src/hello.js + web-export: true diff --git a/docs/examples/open_api_spec.json b/docs/examples/open_api_spec.json new file mode 100644 index 000000000..94aa09940 --- /dev/null +++ b/docs/examples/open_api_spec.json @@ -0,0 +1,60 @@ +{ + "swagger": "2.0", + "info": { + "version": "1.0", + "title": "Hello World API" + }, + "basePath": "/hello", + "schemes": [ + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/world": { + "get": { + "description": "Returns a greeting to the user!", + "operationId": "hello_world", + "responses": { + "200": { + "description": "Returns the greeting.", + "schema": { + "type": "string" + } + } + } + } + } + + }, + "x-gateway-configuration": { + "assembly": { + "execute": [ + { + "operation-switch": { + "case": [ + { + "operations": [ + "getHello" + ], + "execute": [ + { + "invoke": { + "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http", + "verb": "keep" + } + } + ] + } + ], + "otherwise": [] + } + } + ] + } + } +} diff --git a/docs/wskdeploy_apigateway_open_api_spec.md b/docs/wskdeploy_apigateway_open_api_spec.md new file mode 100644 index 000000000..01451d516 --- /dev/null +++ b/docs/wskdeploy_apigateway_open_api_spec.md @@ -0,0 +1,177 @@ + + +# API Gateway + +## The "Hello World" API + +This example builds on the ["Hello World" Action](wskdeploy_action_helloworld.md#actions) example and ["Hello World" API](wdkdeploy_apigateway_helloworld.md) example by adding an Open API Specification to define an API that is invoked via an API call. + +It shows how to: +- update the Action named ‘hello_world’ to expose it to the gateway. +- specify the API's endpoint that will trigger the action via an Open API Specification. + +### Manifest file +#### _Example: “Hello world” action with project config to point to the API spec_ +```yaml +project: + config: open_api_spec.json + packages: + hello_world_package: + version: 1.0 + license: Apache-2.0 + actions: + hello_world: + function: src/hello.js + web-export: true +``` +### Open API Specification +#### _Example: "Hello world" open api specification_ +```json +{ + "swagger": "2.0", + "info": { + "version": "1.0", + "title": "Hello World API" + }, + "basePath": "/hello", + "schemes": [ + "https" + ], + "consumes": [ + "application/json" + ], + "produces": [ + "application/json" + ], + "paths": { + "/world": { + "get": { + "description": "Returns a greeting to the user!", + "operationId": "hello_world", + "responses": { + "200": { + "description": "Returns the greeting.", + "schema": { + "type": "string" + } + } + } + } + } + + }, + "x-gateway-configuration": { + "assembly": { + "execute": [ + { + "operation-switch": { + "case": [ + { + "operations": [ + "getHello" + ], + "execute": [ + { + "invoke": { + "target-url": "https://openwhisk.ng.bluemix.net/api/some/action/path.http", + "verb": "keep" + } + } + ] + } + ], + "otherwise": [] + } + } + ] + } + } +} +``` +*NOTE*: Some providers such as IBM may have changed these keys. For example, IBM uses `x-ibm-configuration` instead of `x-gateway-configuration`. + +There are two major differences from _"Hello World" API_ example: +- the root key is now project as the open api specification is a project wide concept. +- a new `config` key specifying where the Open API Specification is located. + +The `config` key under `project` in the manifest file specifies where the Open API Specification is located. The keyword `config` was chosen to remain consistent with the OpenWhisk CLI flag option. The Open API Specification describes in a JSON document the the base path, endpoint, HTTP verb, and other details describing the API. For example, the document above describes a GET endpoint at `/hello/world` that recieves JSON as input and returns JSON as output. + +### Deploying + +You cannot deploy the "hello world API gateway Open API Specification" manifest from the openwhisk-wskdeploy project directory directly. You need to update the `target-url`. This valued will be specific to your deployment/provider. An example of such a URL would be: `https://us-south.functions.cloud.ibm.com/api/v1/web/jdoe@ibm.com/hello_world_package/hello_world.json`. After filling out that value, you would deploy via: + +```sh +$ wskdeploy -m docs/examples/manifest_hello_world_apigateway_open_api_spec.yaml +``` + +### Invoking + +Check the full URL of your API first: +```sh +$ wsk api list +``` + +This will return some information on the API, including the full URL, which +should end with `hello/world`. It can then be invoked: + +```sh +$ curl +``` + +### Result +The invocation should return a JSON response that includes this result: + +```json +{ + "greeting": "Hello, undefined from undefined" +} +``` + +The output parameter '```greeting```' contains "_undefined_" values for the '```name```' and '```place```' input parameters as they were not provided in the manifest or the HTTP call. You can provide them as query parameters: + +```sh +$ curl ?name=World&place=Earth +``` + +### Discussion + +This "hello world" example represents the minimum valid Manifest file which includes only the required parts of the Project, Package, Action and Open API Specification location. + +### Source code +The source code for the manifest and JavaScript files can be found here: +- [manifest_hello_world_apigateway.yaml](examples/manifest_hello_world_apigateway_open_api_spec.yaml) +- [open_api_spec.json](examples/open_api_spec.json) +- [hello.js](examples/src/hello.js) + +--- + + +
+ + + + + + +
<< previousExample Indexnext >>
+
+