OpenAPI AsyncAPI proxy example (#151)

* OpenAPI AsyncAPI proxy example

* Update descriptions and external docs URL

* Simplify compose stack

* Update POST example

openapi.asyncapi.proxy/README.md

@@ -0,0 +1,37 @@
+# openapi.asyncapi.proxy
+## Running locally
+
+This example runs using Docker compose. You will find the setup scripts in the [compose](./docker/compose) folder.
+
+### Setup
+
+The `setup.sh` script will:
+
+- Configure Zilla instance
+
+```bash
+./compose/setup.sh
+```
+
+### Test
+
+#### Create Pet
+```bash
+curl -X POST --location 'http://localhost:7114/pets' \
+     --header 'Content-Type: application/json' \
+     --header 'Idempotency-Key: 1' \
+     --data '{ "id": 1, "name": "Spike" }'
+```
+
+#### Retrieve Pets
+```bash
+curl --location 'http://localhost:7114/pets' --header 'Accept: application/json'
+```
+
+### Teardown
+
+The `teardown.sh` script will remove any resources created.
+
+```bash
+./compose/teardown.sh
+```

openapi.asyncapi.proxy/docker/compose/docker-compose.yaml

@@ -0,0 +1,20 @@
+services:
+  zilla:
+    image: ghcr.io/aklivity/zilla:${ZILLA_VERSION}
+    container_name: zilla
+    pull_policy: always
+    restart: unless-stopped
+    ports:
+      - 7114:7114
+      - 4444:4444
+    environment:
+      ZILLA_INCUBATOR_ENABLED: "true"
+    volumes:
+      - ../../specs/http-openapi.yaml:/etc/zilla/http-openapi.yaml
+      - ../../specs/kafka-asyncapi.yaml:/etc/zilla/kafka-asyncapi.yaml
+      - ../../zilla.yaml:/etc/zilla/zilla.yaml
+    command: start -v -e
+
+networks:
+  default:
+    driver: bridge

openapi.asyncapi.proxy/docker/compose/setup.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+set -e
+
+NAMESPACE="${NAMESPACE:-zilla-openapi-asyncapi-proxy}"
+export ZILLA_VERSION="${ZILLA_VERSION:-latest}"
+export KAFKA_BROKER="${KAFKA_BROKER:-kafka}"
+export KAFKA_BOOTSTRAP_SERVER="${KAFKA_BOOTSTRAP_SERVER:-host.docker.internal:9092}"
+export KAFKA_PORT="${KAFKA_PORT:-9092}"
+INIT_KAFKA="${INIT_KAFKA:-true}"
+
+# Start or restart Zilla
+if [[ -z $(docker compose -p $NAMESPACE ps -q zilla) ]]; then
+  echo "==== Running the $NAMESPACE example with $KAFKA_BROKER($KAFKA_BOOTSTRAP_SERVER) ===="
+  docker compose -p $NAMESPACE up -d
+
+  # Create topics in Kafka
+  if [[ $INIT_KAFKA == true ]]; then
+    docker run --rm bitnami/kafka:3.2 bash -c "
+    echo 'Creating topics for $KAFKA_BOOTSTRAP_SERVER'
+    /opt/bitnami/kafka/bin/kafka-topics.sh --bootstrap-server $KAFKA_BOOTSTRAP_SERVER --create --if-not-exists --topic petstore-pets --config cleanup.policy=compact
+    "
+  fi
+
+else
+  docker compose -p $NAMESPACE up -d --force-recreate --no-deps zilla
+fi

openapi.asyncapi.proxy/docker/compose/teardown.sh

@@ -0,0 +1,5 @@
+#!/bin/bash
+set -e
+
+NAMESPACE="${NAMESPACE:-zilla-openapi-asyncapi-proxy}"
+docker compose -p $NAMESPACE down --remove-orphans

openapi.asyncapi.proxy/specs/http-openapi.yaml

@@ -0,0 +1,80 @@
+---
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: Swagger Petstore
+  license:
+    name: MIT
+servers:
+  - url: http://localhost:7114
+paths:
+  "/pets":
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - pets
+      responses:
+        '200':
+          description: A paged array of pets
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Pets"
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+    post:
+      summary: Create a pet
+      operationId: createPet
+      tags:
+        - pets
+      requestBody:
+        content:
+          application/json:
+            schema:
+              "$ref": "#/components/schemas/Pet"
+        required: true
+      responses:
+        '201':
+          description: Null response
+        default:
+          description: unexpected error
+          content:
+            application/json:
+              schema:
+                "$ref": "#/components/schemas/Error"
+components:
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string
+    Pets:
+      type: array
+      maxItems: 100
+      items:
+        "$ref": "#/components/schemas/Pet"
+    Error:
+      type: object
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: integer
+          format: int32
+        message:
+          type: string

openapi.asyncapi.proxy/specs/kafka-asyncapi.yaml

@@ -0,0 +1,126 @@
+#
+# Copyright 2021-2023 Aklivity Inc.
+#
+# Aklivity licenses this file to you under the Apache License,
+# version 2.0 (the "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at:
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+#
+
+asyncapi: 3.0.0
+info:
+  title: Zilla Petstore Kafka API
+  version: 2.0.0
+  description: >
+    This Petstore specification illustrates how Zilla can proxy OpenAPI-defined
+    REST APIs to AsyncAPI-defined Kafka APIs.
+  license:
+    name: Aklivity Community License
+    url: https://github.com/aklivity/zilla/blob/main/LICENSE
+  contact:
+    name: Aklivity Community
+    url: https://www.aklivity.io/slack
+  externalDocs:
+    description: Examples Repo
+    url: https://github.com/aklivity/zilla-examples/tree/main/openapi.asyncapi.proxy#readme
+  tags:
+    - name: pet
+      description: Everything about your Pets
+defaultContentType: application/json
+servers:
+  plain:
+    host: host.docker.internal:9092
+    protocol: kafka
+channels:
+  pets:
+    address: "petstore-pets"
+    messages:
+      pet:
+        $ref: "#/components/messages/pet"
+      empty:
+        $ref: "#/components/messages/empty"
+    description: The topic on which pet values may be produced and consumed.
+operations:
+  listPets:
+    action: receive
+    channel:
+      $ref: "#/channels/pets"
+    summary: >-
+      List all pets.
+    messages:
+      - $ref: "#/channels/pets/messages/pet"
+  createPet:
+    action: send
+    channel:
+      $ref: "#/channels/pets"
+    summary: >-
+      Create a pet.
+    messages:
+      - $ref: "#/channels/pets/messages/pet"
+  listPetById:
+    action: receive
+    channel:
+      $ref: "#/channels/pets"
+    summary: >-
+      List a pet by id.
+    messages:
+      - $ref: "#/channels/pets/messages/pet"
+  updatePet:
+    action: send
+    channel:
+      $ref: "#/channels/pets"
+    summary: >-
+      Update an existing Pet.
+    messages:
+      - $ref: "#/channels/pets/messages/pet"
+  deletePet:
+    action: send
+    channel:
+      $ref: "#/channels/pets"
+    summary: >-
+      Deletes a pet.
+    messages:
+      - $ref: "#/channels/pets/messages/empty"
+components:
+  messages:
+    empty:
+      name: EmptyMessage
+      payload:
+        type: "null"
+    pet:
+      name: Pet
+      title: Pet
+      summary: Inform about Pet.
+      contentType: application/json
+      payload:
+        $ref: "#/components/schemas/Pet"
+    pets:
+      name: Pets
+      title: Pets
+      summary: A list of Pets.
+      contentType: application/json
+      payload:
+        type: array
+        items:
+          $ref: "#/components/schemas/Pet"
+  schemas:
+    Pet:
+      type: object
+      required:
+        - id
+        - name
+      properties:
+        id:
+          type: integer
+          format: int64
+        name:
+          type: string
+        tag:
+          type: string

openapi.asyncapi.proxy/zilla.yaml

@@ -0,0 +1,57 @@
+---
+name: zilla-openapi-proxy
+catalogs:
+  host_filesystem:
+    type: filesystem
+    options:
+      subjects:
+        http:
+          path: http-openapi.yaml
+        kafka:
+          path: kafka-asyncapi.yaml
+bindings:
+  north_openapi_server:
+    type: openapi
+    kind: server
+    options:
+      specs:
+        my-openapi-spec:
+          catalog:
+            host_filesystem:
+              subject: http
+    exit: north_openapi_asyncapi_proxy
+  north_openapi_asyncapi_proxy:
+    type: openapi-asyncapi
+    kind: proxy
+    options:
+      specs:
+        openapi:
+          my-openapi-spec:
+            catalog:
+              host_filesystem:
+                subject: http
+        asyncapi:
+          my-asyncapi-spec:
+            catalog:
+              host_filesystem:
+                subject: kafka
+    routes:
+      - exit: south_asyncapi_client
+        when:
+          - api-id: my-openapi-spec
+        with:
+          api-id: my-asyncapi-spec
+  south_asyncapi_client:
+    type: asyncapi
+    kind: client
+    options:
+      specs:
+        my-asyncapi-spec:
+          catalog:
+            host_filesystem:
+              subject: kafka
+telemetry:
+  exporters:
+    stdout_logs_exporter:
+      type: stdout
+