Using an OpenAPI Definition

Let's use a developer-first approach and host your API, which uses an OpenAPI definition, on WSO2 API Microgateway using the WSO2 Microgateway runtime.

Before you begin...

Make sure to install and set up all the installation prerequisites.

Step 1 - Generate an executable using WSO2 API Microgateway Toolkit

Step 1.1 - Initialize a project

  1. Navigate to a preferred workspace folder using the command line to set the location that is used to store the Microgateway project.

  2. Create a project named "petstore" by running the following command. This will create the folder structure for the artifacts to be included.

    micro-gw init petstore

    The project is now initialized. A directory with the name "petstore" has been created within the directory where you executed the init command.

    Info

    More Information - For more information on the MGW project directory that gets created, see Project Directory .

Step 1.2 - Build the project

  1. Add the OpenAPI definition to the project. Navigate to the /petstore/api_definitions directory. Add the API definition(s) to this directory. Let's use the Petstore sample open API definition.

    Info

    If you open the Open API Specification (OAS) document of the Petstore API using a text editor, you will notice the resource (path) definitions of the API following the standard Open API Specification. You will also see the target server (back-end) URL of the API under the "x-wso2-production-endpoints" OAS vendor extension. WSO2 Microgateway uses this interface definition and the target server URL to generate a gateway proxy for the Petstore API.

  2. Use your command line tool to navigate to where the project directory ("petstore") was created and execute the following command to build the project An executable jar file (/petstore/target/petstore.jar) is created to expose the API via WSO2 API Microgateway.

    micro-gw build petstore

Step 2 - Run the API Microgateway

The executable jar file (.jar), which includes the API artifacts of the project, is used as input to the WSO2 API Microgateway runtime component for the purpose of exposing the APIs. Follow the steps below to expose the APIs via WSO2 API Microgateway.

  1. Execute the following command to start WSO2 API Microgateway.

    gateway <path-to-MGW-jar-file>
    gateway /Users/kim/Downloads/TestProj/petstore-project/target/petstore-project.jar

    When WSO2 Microgateway starts successfully, the following log is printed on the console.

    ballerina: HTTP access log enabled
[ballerina/http] started HTTPS/WSS endpoint 0.0.0.0:9096
[ballerina/http] started HTTPS/WSS endpoint 0.0.0.0:9095
[ballerina/http] started HTTP/WS endpoint 0.0.0.0:9090
2019-05-30 18:09:32,540 INFO  [wso2/gateway] - HTTPS listener is active on port 9095 
2019-05-30 18:09:32,541 INFO  [wso2/gateway] - HTTP listener is active on port 9090

Step 3 - Invoke the sample API

Step 3.1 - Obtain a token

After the APIs are exposed via WSO2 API Microgateway, you can invoke an API with a valid token(JWT or opaque access token) or an API key. Lets use a sample JWT to access the API. Following JWT is a trusted by the default micorgayeway client certificate trust store.

The below command will set the sample JWT to the shell variable TOKEN.

TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5UZG1aak00WkRrM05qWTBZemM1TW1abU9EZ3dNVEUzTVdZd05ERTVNV1JsWkRnNE56YzRaQT09In0.eyJhdWQiOiJodHRwOlwvXC9vcmcud3NvMi5hcGltZ3RcL2dhdGV3YXkiLCJzdWIiOiJhZG1pbkBjYXJib24uc3VwZXIiLCJhcHBsaWNhdGlvbiI6eyJvd25lciI6ImFkbWluIiwidGllclF1b3RhVHlwZSI6InJlcXVlc3RDb3VudCIsInRpZXIiOiIxMFBlck1pbiIsIm5hbWUiOiJqd3QiLCJpZCI6MzMsInV1aWQiOm51bGx9LCJzY29wZSI6ImFtX2FwcGxpY2F0aW9uX3Njb3BlIGRlZmF1bHQiLCJpc3MiOiJodHRwczpcL1wvbG9jYWxob3N0Ojk0NDNcL29hdXRoMlwvdG9rZW4iLCJ0aWVySW5mbyI6eyJVbmxpbWl0ZWQiOnsidGllclF1b3RhVHlwZSI6InJlcXVlc3RDb3VudCIsInN0b3BPblF1b3RhUmVhY2giOnRydWUsInNwaWtlQXJyZXN0TGltaXQiOjAsInNwaWtlQXJyZXN0VW5pdCI6bnVsbH19LCJrZXl0eXBlIjoiUFJPRFVDVElPTiIsInN1YnNjcmliZWRBUElzIjpbeyJzdWJzY3JpYmVyVGVuYW50RG9tYWluIjoiY2FyYm9uLnN1cGVyIiwibmFtZSI6IlBpenphU2hhY2tBUEkiLCJjb250ZXh0IjoiXC9waXp6YXNoYWNrXC8xLjAuMCIsInB1Ymxpc2hlciI6ImFkbWluIiwidmVyc2lvbiI6IjEuMC4wIiwic3Vic2NyaXB0aW9uVGllciI6IlVubGltaXRlZCJ9XSwiY29uc3VtZXJLZXkiOiJheFduaVZHZWpQaFRCVGR2OFNidjVjcmdRaE1hIiwiZXhwIjozNzM2MDY2NTY3LCJpYXQiOjE1ODg1ODI5MjAsImp0aSI6ImZjZGIwY2M1LTRjNWUtNDZkOC04OTliLTMxZDJhNmMyZGUxZSJ9.KjNXGc1xNx_zuxg0mW_i8oGE517Y6ewJEWL9WBRXaCgEEYFYyLl-44bd18093QrYB3CkStKuw6_GTAvP_J6HEu9rO44vXhPNHosx_fB0t4n8OO9Gimp882syMiwy9mbpz4NEdMnrdTj-4l-7cCR4YrVcvdd_Z2zlQ9xLx_tq8gTLecnchE7Mb9dCQHgePjzh9a4OTpGparkyi-XOJ12ywyYhjwQK1C2uzyqeE0XpQzFzMZDtEktNmsP-AAEne27DVcvepJsUgDihhWQzsXBmnYV6zPHKG3pXlFCVhnVPIiC6RIA94tMle2_WjqFNZNQx0HqJyIH_vb2WeSO6DeUMvA

Step 3.2 - Invoke the API

Execute the following cURL command to Invoke the API using the JWT.

curl -X GET "https://<MGW-runtime-hostname>:<MGW-runtime-port>/<API-context>/<API-resource>" -H "accept:application/xml" -H "Authorization:Bearer $TOKEN" -k
curl -X GET "https://localhost:9095/petstore/v1/pet/1" -H "accept: application/xml" -H "Authorization:Bearer $TOKEN" -k
Top