Skip to main 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.

Extensions that work with requests:​

  • CORS - How to specify CORS settings.
  • Rate-Limiting - How to rate-limit requests to your API.
  • Routing - How to configure routing of API requests.
  • Validation - How work with automatic request validation.
  • Timeouts - How to set request timeouts.
  • Authentication - How to set authentication of your API.

Extensions that work with responses:​

  • Mocking - How to mock all or parts of your API.
  • Cache - How to cache your API responses.

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​

The x-kusk extension at the operation level takes precedence, or overrides, what is specified at the path level, including the disabled option. Likewise, the path level settings override what is specified at the global level.

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