Please Help

This page describes important known issues with our API documentation. If you have an idea that helps us fixing them efficiently, please file an issue or start a discussion on GitHub. If you like, a ZITADEL shirt is headed your way once the issue is fixed based on your input 🙏

Generated Examples for oneOf Fields

The generated examples for mutually exclusive oneOf fields are not correct.

Let's take the ListUserGrants docs as an example. The example suggests that the queries field is an array a single object that takes all the queries in its object properties:

{
  "query": {
    "offset": "0",
    "limit": 100,
    "asc": true
  },
  "queries": [
    {
      "projectIdQuery": {
        "projectId": "69629023906488334"
      },
      "userIdQuery": {
        "userId": "69629023906488334"
      },
      "withGrantedQuery": {
        "withGranted": true
      }
    }
  ]
}

However, the correct way to represent this is to have the queries as separate items in the queries array:

{
  "query": {
    "offset": "0",
    "limit": 100,
    "asc": true
  },
  "queries": [
    {
      "projectIdQuery": {
        "projectId": "69629023906488334"
      }
    }, {
      "userIdQuery": {
        "userId": "69629023906488334"
      }
    }, {
      "withGrantedQuery": {
        "withGranted": true
      }
    }
  ]
}

The protoc grpc-gateway plugin generates OpenAPI v2 files that are used to generate the examples. OpenAPI v3 supports the oneOf keyword but OpenAPI v2 doesn't. The grpc-gateway plugin therefore just flattens the proto oneof fields into the messages properties where they are defined.