Hi all,
In the mail thread [ARCHITECTURE] [APIM] SwaggerHub Integration with WSO2,
I gave you an introduction to the project that I am working on. In this
mail, I will describe how I handle the payload of creating an API in the
cloud in the plugin that I implement for the Swagger Hub.
Here is the sample payload to create the sample PizzaShackAPI in the cloud
as in the documentation of WSO2 API manager version 2.1.0.
{
"name": "PizzaShackAPI",
"description": "This document describe a RESTFul API for Pizza
Shack online pizza delivery store.\r\n",
"context": "/pizzashack",
"version": "1.0.0",
"provider": "admin",
"apiDefinition":
"{\"paths\":{\"/order\":{\"post\":{\"x-auth-type\":\"Application &
Application User\",\"x-throttling-tier\":\"Unlimited\",\"description\":\"Create
a new
Order\",\"parameters\":[{\"schema\":{\"$ref\":\"#/definitions/Order\"},\"description\":\"Order
object that needs to be
added\",\"name\":\"body\",\"required\":true,\"in\":\"body\"}],\"responses\":{\"201\":{\"headers\":{\"Location\":{\"description\":\"The
URL of the newly created
resource.\",\"type\":\"string\"}},\"schema\":{\"$ref\":\"#/definitions/Order\"},\"description\":\"Created.\"}}}},\"/menu\":{\"get\":{\"x-auth-type\":\"Application
& Application
User\",\"x-throttling-tier\":\"Unlimited\",\"description\":\"Return
a list of available menu
items\",\"parameters\":[],\"responses\":{\"200\":{\"headers\":{},\"schema\":{\"title\":\"Menu\",\"properties\":{\"list\":{\"items\":{\"$ref\":\"#/definitions/MenuItem\"},\"type\":\"array\"}},\"type\":\"object\"},\"description\":\"OK.\"}}}}},\"schemes\":[\"https\"],\"produces\":[\"application/json\"],\"swagger\":\"2.0\",\"definitions\":{\"MenuItem\":{\"title\":\"Pizza
menu
Item\",\"properties\":{\"price\":{\"type\":\"string\"},\"description\":{\"type\":\"string\"},\"name\":{\"type\":\"string\"},\"image\":{\"type\":\"string\"}},\"required\":[\"name\"]},\"Order\":{\"title\":\"Pizza
Order\",\"properties\":{\"customerName\":{\"type\":\"string\"},\"delivered\":{\"type\":\"boolean\"},\"address\":{\"type\":\"string\"},\"pizzaType\":{\"type\":\"string\"},\"creditCardNumber\":{\"type\":\"string\"},\"quantity\":{\"type\":\"number\"},\"orderId\":{\"type\":\"integer\"}},\"required\":[\"orderId\"]}},\"consumes\":[\"application/json\"],\"info\":{\"title\":\"PizzaShackAPI\",\"description\":\"This
document describe a RESTFul API for Pizza Shack online pizza delivery
store.\\n\",\"license\":{\"name\":\"Apache
2.0\",\"url\":\"http://www.apache.org/licenses/LICENSE-2.0.html\"},\"contact\":{\"email\":\"[email protected]\",\"name\":\"John
Doe\",\"url\":\"http://www.pizzashack.com\"},\"version\":\"1.0.0\"}}";,
"wsdlUri": null,
"status": "PUBLISHED",
"responseCaching": "Disabled",
"cacheTimeout": 300,
"destinationStatsEnabled": false,
"isDefaultVersion": false,
"type": "HTTP",
"transport": [
"http",
"https"
],
"tags": ["pizza"],
"tiers": ["Unlimited"],
"maxTps": {
"sandbox": 5000,
"production": 1000
},
"visibility": "PUBLIC",
"visibleRoles": [],
"visibleTenants": [],
"endpointConfig":
"{\"production_endpoints\":{\"url\":\"https://localhost:9443/am/sample/pizzashack/v1/api/\",\"config\":null},\"sandbox_endpoints\":{\"url\":\"https://localhost:9443/am/sample/pizzashack/v1/api/\",\"config\":null},\"endpoint_type\":\"http\"}";,
"endpointSecurity": {
"username": "user",
"type": "basic",
"password": "pass"
},
"gatewayEnvironments": "Production and Sandbox",
"sequences": [],
"subscriptionAvailability": null,
"subscriptionAvailableTenants": [],
"businessInformation": {
"businessOwnerEmail": "[email protected]",
"technicalOwnerEmail": "[email protected]",
"technicalOwner": "John Doe",
"businessOwner": "Jane Roe"
},
"corsConfiguration": {
"accessControlAllowOrigins": ["*"],
"accessControlAllowHeaders": [
"authorization",
"Access-Control-Allow-Origin",
"Content-Type",
"SOAPAction"
],
"accessControlAllowMethods": [
"GET",
"PUT",
"POST",
"DELETE",
"PATCH",
"OPTIONS"
],
"accessControlAllowCredentials": false,
"corsConfigurationEnabled": false
}
}
But I used only the mandatory elements of the payload for creating because
I had to create a POJO for handling the payload. Here is the payload with
the mandatory elements.
{
"name": "Simple Inventory API",
"context": "/simple",
"version": "1.0.0",
"description": "This is a simple API",
"apiDefinition":
"{\"swagger\":\"2.0\",\"info\":{\"description\":\"This is a simple
API\",\"version\":\"1.0.0\",\"title\":\"Simple Inventory
API\",\"contact\":{\"email\":\"[email protected]\"},\"license\":{\"name\":\"Apache
2.0\",\"url\":\"http://www.apache.org/licenses/LICENSE-2.0.html\"}},\"host\":\"virtserver.swaggerhub.com\",\"basePath\":\"/simple\",\"tags\":[{\"name\":\"admins\",\"description\":\"Secured
Admin-only calls\"},{\"name\":\"developers\",\"description\":\"Operations
available to regular
developers\"}],\"schemes\":[\"https\"],\"paths\":{\"/inventory\":{\"get\":{\"tags\":[\"developers\"],\"summary\":\"searches
inventory\",\"description\":\"By passing in the appropriate options,
you can search for\\navailable inventory in the
system\\n\",\"operationId\":\"searchInventory\",\"produces\":[\"application/json\"],\"parameters\":[{\"name\":\"searchString\",\"in\":\"query\",\"description\":\"pass
an optional search string for looking up
inventory\",\"required\":false,\"type\":\"string\"},{\"name\":\"skip\",\"in\":\"query\",\"description\":\"number
of records to skip for
pagination\",\"required\":false,\"type\":\"integer\",\"minimum\":0,\"format\":\"int32\"},{\"name\":\"limit\",\"in\":\"query\",\"description\":\"maximum
number of records to
return\",\"required\":false,\"type\":\"integer\",\"maximum\":50,\"minimum\":0,\"format\":\"int32\"}],\"responses\":{\"200\":{\"description\":\"search
results matching
criteria\",\"schema\":{\"type\":\"array\",\"items\":{\"$ref\":\"#/definitions/InventoryItem\"}}},\"400\":{\"description\":\"bad
input parameter\"}}},\"post\":{\"tags\":[\"admins\"],\"summary\":\"adds
an inventory item\",\"description\":\"Adds an item to the
system\",\"operationId\":\"addInventory\",\"consumes\":[\"application/json\"],\"produces\":[\"application/json\"],\"parameters\":[{\"in\":\"body\",\"name\":\"inventoryItem\",\"description\":\"Inventory
item to
add\",\"required\":false,\"schema\":{\"$ref\":\"#/definitions/InventoryItem\"}}],\"responses\":{\"201\":{\"description\":\"item
created\"},\"400\":{\"description\":\"invalid input, object
invalid\"},\"409\":{\"description\":\"an existing item already
exists\"}}}}},\"definitions\":{\"InventoryItem\":{\"type\":\"object\",\"required\":[\"id\",\"manufacturer\",\"name\",\"releaseDate\"],\"properties\":{\"id\":{\"type\":\"string\",\"format\":\"uuid\",\"example\":\"d290f1ee-6c54-4b01-90e6-d701748f0851\"},\"name\":{\"type\":\"string\",\"example\":\"Widget
Adapter\"},\"releaseDate\":{\"type\":\"string\",\"format\":\"int32\",\"example\":\"2016-08-29T09:12:33.001Z\"},\"manufacturer\":{\"$ref\":\"#/definitions/Manufacturer\"}}},\"Manufacturer\":{\"required\":[\"name\"],\"properties\":{\"name\":{\"type\":\"string\",\"example\":\"ACME
Corporation\"},\"homePage\":{\"type\":\"string\",\"format\":\"url\",\"example\":\"https://www.acme-corp.com\"},\"phone\":{\"type\":\"string\",\"example\":\"408-867-5309\"}}}}}";,
"isDefaultVersion": false,
"transport": ["http", "https"],
"tiers": ["Unlimited"],
"visibility": "PUBLIC",
"endpointConfig": "",
"corsConfiguration": {
"corsConfigurationEnabled": false
}
}
More about the payload,
Note : After an integration is enabled with WSO2 API management cloud from
the Swagger Hub and saving, the API should be created in the WSO2 API
management cloud in the CREATED state.
- The following elements of the payload are set as default values as the
cloud user can change these values any time before publishing the API.
- visibility to PUBLIC
- tiers to UNLIMITED
- corsConfiguration to false
- endpointConfig to null
- The provider element will be returned with the response after
creating the API in the cloud with the appropriate username of the cloud
user according to the access token the user provide when enabling the
integration with the cloud from the Swagger Hub.
- Some swagger definitions generated by the Swagger Hub doesn't contain
the "basePath" element. You can see a swagger definition without the
basePath in this link
<https://app.swaggerhub.com/apis/user1/OAuth2Application/1.0.0>[1]. So
the swagger definition is checked for the basePath before exporting. If a
basePath is not in the definition, the user will have to enter a basePath
to the definition and export.
- These elements are mapped from the swagger definition to the payload
- title -> name
- version -> version
- description -> description
- basePath -> context
Any feedback is appreciated.
Thank you,
-----------------------------------------------------------------------------------------------------------------------------------------------------
[1] https://app.swaggerhub.com/apis/user1/OAuth2Application/1.0.0
[2] Refer the mail thread : [ARCHITECTURE] [APIM] SwaggerHub Integration
with WSO2
Akila Aroshana
Software Engineer (Intern)
WSO2
Mobile : +94702178247
Email : [email protected]
LinkedIn : www.linkedin.com/in/akila-amarasinghe
_______________________________________________
Architecture mailing list
[email protected]
https://mail.wso2.org/cgi-bin/mailman/listinfo/architecture
