Skip to main content

OpenAPI Overlays

Kusk supports code-first approaches, i.e. OpenAPI generated from code annotations, by use of OpenAPI Overlays.

OpenAPI Overlays is a new specification that allows you to have an OpenAPI file without any Kusk extensions, and an overlay file containing the extenions you would want to add to your OpenAPI definition.

After merging the overlay with the OpenAPI file, the resulting file is an OpenAPI definition with all the metadata added to it, ready to be deployed by Kusk.

This way, teams can generate their OpenAPI from code, and then add the gateway deployment metadata later.

Example

Let's start with an OpenAPI definition that does not have any Kusk extensions added to it.

openapi: 3.0.0
servers:
- url: http://api.mydomain.com
info:
title: simple-api
version: 0.1.0
paths:
/hello:
get:
summary: Returns a Hello world to the user
responses:
'200':
description: A simple hello world!
content:
application/json; charset=utf-8:
schema:
type: object
properties:
message:
type: string
required:
- message

Now let's create an overlay that adds Kusk mocking policy to our OpenAPI definition.

overlays: 1.0.0
extends: ./openapi.yaml
actions:
- target: "$"
update:
mocking:
enabled: true

To apply the overlay to the OpenAPI definition, run:

kusk deploy --overlay overlay.yaml
Expected output
🎉 successfully parsed
✅ initiallizing deployment to fleet kusk-gateway-envoy-fleet
api.gateway.kusk.io/simple-api created

If you want to look at the generated OpenAPI file before deploying it to Kusk, you can run:

kusk generate --overlay overlay.yaml
Expected output
apiVersion: gateway.kusk.io/v1alpha1
kind: API
metadata:
name: simple-api
namespace: default
spec:
fleet:
name: kusk-gateway-envoy-fleet
namespace: kusk-system
spec: |
openapi: 3.0.0
servers:
- url: http://api.mydomain.com
components: {}
info:
title: simple-api
version: 0.1.0
x-kusk:
mocking:
enabled: true
paths:
/hello:
get:
responses:
"200":
content:
application/json; charset=utf-8:
schema:
properties:
message:
type: string
required:
- message
type: object
description: A simple hello world!
summary: Returns a Hello world to the user

Overlay reference:

  • target - property is a JSONPath selector (currently proposed by OpenAPI initiative is JMESPath).
  • extends - defines which API spec to “extend” or which API spec should be overlayed. The value must be in form of full path either as relative or absolute path. For example extends: overlay.yaml won't work but extends: ./overlay.yaml will
  • update - property should be a valid YAML that will be placed in the target object
  • remove - property is a boolean - indicates that the selected target should be removed