Is description supported when importing event types from an OpenAPI document?

[mderriey]

Hi 👋

We're leveraging the capability to import event types from an OpenAPI document.

The docs mention the following:

When the event type already exists, it'll be updated with the latest description and schema, otherwise a new event type will be created.

We can't seem to get the description to go through; we've tried defining it at several levels, with no success.

Click to see a cut-down example of the OpenAPI document we use

{
  "openapi": "3.1.0",
  "info": {
    "title": "Webhook",
    "version": "1.0.0"
  },
  "webhooks": {
    "RedactedEventType": {
      "description": "Description.",
      "summary": "Description.",
      "post": {
        "description": "Description.",
        "requestBody": {
          "description": "Description.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RedactedEvent"
              },
              "example": {
                "type": "RedactedEventType",
                "data": {
                  "RedactedPropertyOne": "<guid>",
                  "RedactedPropertyTwo": "<guid>"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "RedactedEvent": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "default": "RedactedEvent",
            "enum": ["RedactedEvent"]
          },
          "data": {
            "type": "object",
            "properties": {
              "RedactedPropertyOne": {
                "type": "string"
              },
              "RedactedPropertyTwo": {
                "type": "string"
              }
            },
            "required": ["RedactedPropertyOne", "RedactedPropertyTwo"]
          }
        },
        "required": ["type", "data"]
      }
    }
  }
}

We also tried looking in the code but weren't able to find the implementation for the /api/v1/event-type/import/openapi/ endpoint.

Could you please help us with this?

[tasn]

I believe so. Looping in @svix-lucho to help!

[svix-lucho]

The description is loaded from the field defined under post, so in this example, it will be 'Description 2':

{
    "openapi": "3.1.0",
    "info": {
        "title": "Webhook",
        "version": "1.0.0"
    },
    "webhooks": {
        "RedactedEventType": {
            "description": "Description 1.",
            "summary": "Description.",
            "post": {
                "description": "Description 2.",
                "requestBody": {
                    "description": "Description 3.",
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/RedactedEvent"
                            },
                            "example": {
                                "type": "RedactedEventType",
                                "data": {
                                    "RedactedPropertyOne": "<guid>",
                                    "RedactedPropertyTwo": "<guid>"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "RedactedEvent": {
                "type": "object",
                "properties": {
                    "type": {
                        "type": "string",
                        "default": "RedactedEvent",
                        "enum": [
                            "RedactedEvent"
                        ]
                    },
                    "data": {
                        "type": "object",
                        "properties": {
                            "RedactedPropertyOne": {
                                "type": "string"
                            },
                            "RedactedPropertyTwo": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "RedactedPropertyOne",
                            "RedactedPropertyTwo"
                        ]
                    }
                },
                "required": [
                    "type",
                    "data"
                ]
            }
        }
    }
}

However, I was able to use your example directly and the description was loaded correctly. I only renamed 'Description' to 'Description 2' for clarity.

[1.129s][~/Desktop]$ jq -n --argjson spec "$(cat ./openapi-example-1.json)" '{"spec":$spec}' | curl -X 'POST' \
  'https://api.eu.svix.com/api/v1/event-type/import/openapi/' \   
  -H 'Authorization: Bearer ***' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d @-


[1.096s][~/Desktop]$ curl -X 'GET' \                                                                           
  'https://api.eu.svix.com/api/v1/event-type/RedactedEventType/' \
  -H 'Authorization: Bearer ***' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' 

 
{"name":"RedactedEventType","description":"Description 2.","archived":false,"schemas":{"1":{"examples":[{"data":{"RedactedPropertyOne":"<guid>","RedactedPropertyTwo":"<guid>"},"type":"RedactedEventType"}],"properties":{"data":{"properties":{"RedactedPropertyOne":{"type":"string"},"RedactedPropertyTwo":{"type":"string"}},"required":["RedactedPropertyOne","RedactedPropertyTwo"],"type":"object"},"type":{"default":"RedactedEvent","enum":["RedactedEvent"],"type":"string"}},"required":["type","data"],"type":"object"}},"createdAt":"2024-03-11T14:12:57.618244Z","updatedAt":"2024-03-11T14:34:12.660941Z","featureFlag":null}%      

[svix-lucho]

@mderriey can you check again if it's working for you? or share a less cut-down example, maybe something else in the spec is causing the issue.

[mderriey]

Thanks a lot for the detailed reply @svix-lucho, much appreciated.

I'm so so sorry, the endpoint is working fine, it was my mistake

I'm using the Postman collection, and I just noticed that all POST endpoints have an idempotency-key header defined with what is supposed to be a placeholder value of <string>. That must have been saved on the backend, and the subsequent requests weren't processed.

I removed it, and it works as expected.

Thanks, and sorry for bothering you with such a stupid mistake.

[mderriey]

Summary that I'll mark as an answer for future peeps who stumble here.

The event type description is sourced from the description field defined under "post", e.g.

{
  "openapi": "3.1.0",
  "info": {
    "title": "Webhooks",
    "version": "1.0.0"
  },
  "webhooks": {
    "RedactedEventType": {
      "post": {
+       "description": "This will be the event type description.",
        "requestBody": {
          // rest omitted for brevity
        }
      }
    }
  }
}

If you're using the provided Postman collection and your event types aren't updated, make sure to disable the idempotency-key header in the request (and all other POST requests)