Kong Gateway Enterprise [ARCHIVE]
0.36-x
PermalinkOpenAPI Spec to Kong Entities
Important: The
/oas-config
endpoint is deprecated and no longer maintained. Instead, convert OpenAPI 3.0 Specs to Declarative Config using Insomnia or Inso CLI. Learn more about generating Kong Declarative Config through the Insomnia app.
This Admin API endpoint allows you to read an OpenAPI Spec into Kong to create the appropriate Services and Routes in an automated way. For now, the functionality is in the early stages and is limited to creating Services and Routes in Kong. This endpoint is useful for testing or quick-start scenarios. In future releases, it may be expanded.
PermalinkCreate Routes & Services using OAS
Endpoint
/oas-config
Attribute | Description |
---|---|
spec |
JSON Body containing a stringified / escaped OAS Specification to generate Kong Routes & Services. |
Response
Returns the Routes & Services generated by the given OAS file as JSON.
HTTP 201 Created
{
"routes": [
{
"created_at": 1568224673,
"https_redirect_status_code": 426,
"id": "a33f22b8-e81f-44ec-b8a2-a8b117800115",
"methods": [
"POST"
],
"paths": [
"/user"
],
"preserve_host": false,
"protocols": [
"http"
],
"regex_priority": 0,
"service": {
"id": "bc64c34e-5c83-49f5-9a8f-65714ceaea65"
},
"strip_path": false,
"updated_at": 1568224673
},
{
"created_at": 1568224673,
"https_redirect_status_code": 426,
"id": "554bb6d3-ce80-435f-8ad2-41cd7ebca5b6",
"methods": [
"GET"
],
"paths": [
"/store/inventory"
],
"preserve_host": false,
"protocols": [
"http"
],
"regex_priority": 0,
"service": {
"id": "bc64c34e-5c83-49f5-9a8f-65714ceaea65"
},
"strip_path": false,
"updated_at": 1568224673
},
{
"created_at": 1568224673,
"https_redirect_status_code": 426,
"id": "2dea6287-d856-4369-8e1b-b55cbf09386b",
"methods": [
"POST",
"PUT"
],
"paths": [
"/pet"
],
"preserve_host": false,
"protocols": [
"http"
],
"regex_priority": 0,
"service": {
"id": "bc64c34e-5c83-49f5-9a8f-65714ceaea65"
},
"strip_path": false,
"updated_at": 1568224673
}
],
"services": [
{
"connect_timeout": 60000,
"created_at": 1568224673,
"host": "petstore.swagger.io",
"id": "bc64c34e-5c83-49f5-9a8f-65714ceaea65",
"name": "swagger-petstore-1",
"path": "/v2",
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1568224673,
"write_timeout": 60000
}
]
}
PermalinkUpdate Routes & Services using OAS
Endpoint
/oas-config
Attribute | Description |
---|---|
spec |
JSON Body containing a stringified / escaped OAS Specification to generate Kong Routes & Services |
recreate_routes |
true to update Service routes |
Response
Return Updated Routes & Services
HTTP 201 Created
}
"services": [
{
"connect_timeout": 60000,
"created_at": 1568224673,
"host": "petstore.swagger.io",
"id": "bc64c34e-5c83-49f5-9a8f-65714ceaea65",
"name": "swagger-petstore-1",
"path": "/v1",
"port": 80,
"protocol": "http",
"read_timeout": 60000,
"retries": 5,
"updated_at": 1568227806,
"write_timeout": 60000
}
]
}
PermalinkExample of how to use the OAS Config Endpoint
- Define your OAS File for the services and routes you wish to create. Please validate your OAS file prior to submitting. The below is an abbreviated version of the sample Petstore specification (https://petstore.swagger.io)[https://petstore.swagger.io].
{ "swagger": "2.0", "info": { "description": "This is a sample server Petstore server. You can find out more about Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/). For this sample, you can use the api key `special-key` to test the authorization filters.", "version": "1.0.0", "title": "Swagger Petstore", "termsOfService": "http://swagger.io/terms/", "contact": { "email": "apiteam@swagger.io" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "host": "petstore.swagger.io", "basePath": "/v2", "tags": [ { "name": "pet", "description": "Everything about your Pets", "externalDocs": { "description": "Find out more", "url": "http://swagger.io" } }, { "name": "store", "description": "Access to Petstore orders" }, { "name": "user", "description": "Operations about user", "externalDocs": { "description": "Find out more about our store", "url": "http://swagger.io" } } ], "schemes": [ "http" ], "paths": { "/pet": { "post": { "tags": [ "pet" ], "summary": "Add a new pet to the store", "description": "", "operationId": "addPet", "consumes": [ "application/json", "application/xml" ], "produces": [ "application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Pet object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Pet" } } ], "responses": { "405": { "description": "Invalid input" } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] }, "put": { "tags": [ "pet" ], "summary": "Update an existing pet", "description": "", "operationId": "updatePet", "consumes": [ "application/json", "application/xml" ], "produces": [ "application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Pet object that needs to be added to the store", "required": true, "schema": { "$ref": "#/definitions/Pet" } } ], "responses": { "400": { "description": "Invalid ID supplied" }, "404": { "description": "Pet not found" }, "405": { "description": "Validation exception" } }, "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ] } }, "/store/inventory": { "get": { "tags": [ "store" ], "summary": "Returns pet inventories by status", "description": "Returns a map of status codes to quantities", "operationId": "getInventory", "produces": [ "application/json" ], "parameters": [], "responses": { "200": { "description": "successful operation", "schema": { "type": "object", "additionalProperties": { "type": "integer", "format": "int32" } } } }, "security": [ { "api_key": [] } ] } }, "/user": { "post": { "tags": [ "user" ], "summary": "Create user", "description": "This can only be done by the logged in user.", "operationId": "createUser", "produces": [ "application/xml", "application/json" ], "parameters": [ { "in": "body", "name": "body", "description": "Created user object", "required": true, "schema": { "$ref": "#/definitions/User" } } ], "responses": { "default": { "description": "successful operation" } } } } } }
- Use the OAS config endpoint to create the Kong Routes and Services based on the above file.
http POST http://kong:8001/oas-config spec=@petstore.json