OpenAPI spec integration with GPT action

[Yuqi-Du]

The OpenAPI spec of Data API failed to import in GPT action. There is a circular reference issue with our current spec right now, a fix is coming. However, even with that fixed, there are multiple other errors occurred in GPT side. And, the fixed spec actually can be validated by other OpenAPI validator or just swagger.

There are multiple unfixed bugs in GPT side for parsing OpenAPI spec right now. https://community.openai.com/t/custom-gpts-action-openapi-3-0-specification-limited-support-oneof-anyof-allof/581015/1 https://community.openai.com/t/parameter-references-are-not-supported/206805 https://community.openai.com/t/openapi-parser-issue-when-all-parsers-say-its-fine-patch-endpoint/277067 https://community.openai.com/t/cant-send-post-request-with-an-array-as-body/599599/2

[Yuqi-Du]

[Yuqi-Du]

Alternate OpenAPI spec validator: https://apitools.dev/swagger-parser/online/#

[phact]

I've been experimenting with the openapi spec for sdk generation and it looks like most of the schema descriptions for request types are wrong.

For example the current CreateCollectionsCommand implies that the body could be:

{
    "name": "collection"
 }

when it actually needs to be:

{
  "createCollection": {
    "name": "collection"
  }
}

Here's the fix for CreateCollectionCommand:

      "CreateCollectionCommand": {
        "description": "Command that creates a collection.",
        "type": object,
        "properties":{
        "required": [
          "createCollection"
        ],
        "createCollection":{
        "type": "object",
        "properties": {
          "name": {
            "description": "Name of the collection",
            "maxLength": 48,
            "minLength": 1,
            "pattern": "[a-zA-Z][a-zA-Z0-9_]*",
            "type": "string"
          },
          "options": {
            "description": "Configuration for the collection",
            "type": "object",
            "properties": {
              "vector": {
                "description": "Vector search index configuration for the collection",
                "type": "object",
                "properties": {
                  "dimension": {
                    "format": "int32",
                    "description": "Dimension of the vector field",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "type": "integer"
                  },
                  "metric": {
                    "description": "Similarity function algorithm that needs to be used for vector search",
                    "default": "cosine",
                    "pattern": "(dot_product|cosine|euclidean)",
                    "type": "string"
                  }
                }
              },
              "vectorize": {
                "description": "Embedding api configuration to support `$vectorize`",
                "type": "object",
                "properties": {
                  "dimension": {
                    "format": "int32",
                    "description": "Dimension of the vector field",
                    "minimum": 0,
                    "exclusiveMinimum": true,
                    "type": "integer"
                  },
                  "metric": {
                    "description": "Similarity function algorithm that needs to be used for vector search",
                    "default": "cosine",
                    "pattern": "(dot_product|cosine|euclidean)",
                    "type": "string"
                  }
                }
              },
              "indexing": {
                "description": "Optional indexing configuration to provide allow/deny list of fields for indexing",
                "type": "object",
                "properties": {
                  "allow": {
                    "description": "List of allowed indexing fields",
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "deny": {
                    "description": "List of denied indexing fields",
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
        }
        }
      },

@Yuki-Du could you have a look? Would be great to get the rest of them fixed.

[tatu-at-datastax]

@phact Thank you! This makes sense.

One note on discrepancy wrt intermediate createCollection: it is probably not something clients should need to worry/know about, but that is part of type metadata for data-binding (by Jackson): so definitions we have are for data/payload. You are probably right in that for client-generation purposes it needs to be modeled as being part of data and not left out even if internally it is separate from class definitions (that is, there is no property createCollection anywhere in POJO hierarchy)

Above is just to add full context for anyone curious about why definition is sort off by one layer.