Using Apicurio Studio with Kuadrant OAS extensions

Using Apicurio with Kuadrant OAS extensions

OpenAPI Extensions can be used to describe extra functionality beyond what is covered by the standard OpenAPI specification. They typically start with x-. Kuadrant OpenAPI extensions start with x-kuadrant, and allow you to configure Kuadrant policy information along side your API.

Apicurio Studio is a UI tool for visualising and editing OpenAPI specifications. It has support for visualising security and extensions defined in your spec.

This guide assumes you have Apicurio Studio already running. See https://www.apicur.io/studio/ for info on how to install Apicurio Studio.

Adding extensions to the spec

Open or import your OpenAPI spec in the Apicurio Studio UI. You can modify the source of the spec from the UI. There are a few different configuration and extension points supported by Apicurio Studio, and also supported by the kuadrantctl cli.

To generate a HTTPRoute for the API, add the following x-kuadrant block to your spec in the UI, replacing values to match your APIs details and the location of your Gateway.

info:
    x-kuadrant:
        route:
            name: petstore
            namespace: petstore
            hostnames:
                - 'petstore.example.com'
            parentRefs:
                -   name: prod-web
                    namespace: kuadrant-multi-cluster-gateways
                    kind: Gateway

See this guide for more info on generating a HTTPRoute.

To generate an AuthPolicy, add a securityScheme to the components block. This securityScheme requires that an API key header is set. Although securityScheme is not an OpenAPI extension, it is used by kuadrantctl like the other extensions mentioned here.

    securitySchemes:
        api_key:
            type: apiKey
            name: api_key
            in: header

When added, the UI will display this in the security requirements section:

See this guide for more info on generating an AuthPolicy.

To generate a RateLimitPolicy for the API, add the following x-kuadrant block to a path in your spec, replacing values to match your APIs details.

paths:
    /:
        x-kuadrant:
            backendRefs:
                -
                    name: petstore
                    namespace: petstore
                    port: 8080
            rate_limit:
                rates:
                    -
                        limit: 2
                        duration: 10
                        unit: second

When added, the UI will show this in Vendor Extensions section for that specific path:

See this guide for more info on generating a RateLimitPoliicy. There is also the full kuadrantctl guide.