Skip to content

The Kusk OpenAPI Extension

Kusk Gateway comes with an x-kusk OpenAPI extension to allow an OpenAPI definition to be the source of truth for both operational and functional aspects of your APIs.

The extension reference describes all available properties, and the following guides are available to help you make the most of them:

  • Mocking - how to mock all or parts of your API
  • Validation - how work with automatic request validation
  • CORS - how to specify CORS settings
  • Routing - how to configure routing of API requests
  • Timeouts - how to set request timeouts

Properties Overview

x-kusk extension can be applied at (not exclusively):

  1. Top level of an OpenAPI definition:
  openapi: 3.0.2
  info:
    title: Swagger Petstore - OpenAPI 3.0
  x-kusk:
    hosts:
    - "example.org"
    disabled: false
    cors:
      ...
  1. Path level:
openapi: 3.0.2
info:
  title: Swagger Petstore - OpenAPI 3.0
paths:
  /pet:
    x-kusk:
      disabled: true # disables all /pet endpoints
    post:
      ...
  1. Method (operation) level:
  openapi: 3.0.2
  info:
    title: Swagger Petstore - OpenAPI 3.0
  paths:
    /pet:
      post:
        x-kusk:
          upstream: # routes the POST /pet endpoint to a Kubernetes service
            service:
              namespace: default
              name: petstore
              port: 8000
        ...

Property Overriding/inheritance

x-kusk extension at the operation level takes precedence, i.e. overrides, what's specified at the path level, including the disabled option. Likewise, the path level settings override what's specified at the global level.

If settings aren't specified at a path or operation level, it will inherit from the layer above. (Operation > Path > Global)