Azure / Azure/azure-rest-api-specs

[EventHub] Swagger doesn't match the API

Open
#19,744 0 comments 0 reactions 0 assignees View on GitHub
Event Hubs Service Attention
Dominant language
TypeSpec
Stars
3.1k
Forks
5.9k
Avg merge
2d 22h
Merged PRs (30d)
444

Description

* Service: `EventHub`
* API Version: `2021-11-01`
* File: `SchemaRegistry.json`
* Field: https://github.com/Azure/azure-rest-api-specs/blob/fbb4e2c74897a67a75116d2a3157bd146262def4/specification/eventhub/resource-manager/Microsoft.EventHub/stable/2021-11-01/SchemaRegistry.json#L255-L261

This field implies a `map[string]string` (or `Dictionary`, depending on your language of choice).

---

Assuming that a resource has been previously deployed with:

```json
"groupProperties": {
"first": "value",
"second": "value",
"third": "value"
}
```

As a user of the API you'd expect that when sending the following payload to the Update API, that the `second` property would be removed:

```json
"groupProperties": {
"first": "value",
"third": "value"
}
```

However it's not - it's left untouched and gets returned:

```json
"groupProperties": {
"first": "value",
"second": "value",
"third": "value"
}
```

.. instead you need to explicitly send `null` as a value here to remove these values:

```json
"groupProperties": {
"first": "value",
"second": null,
"third": "value"
}
```

which then does what you'd expect:

```json
"groupProperties": {
"first": "value",
"third": "value"
}
```

---

Unfortunately this is behaviourally different to every other API in Azure and whilst this maybe legacy behaviour, I believe this is a bug.

It turns out that the Azure SDK outputs this as a `map[string]*string` ([Track2](https://github.com/Azure/azure-sdk-for-go/blob/21f6363dbd925271ca5c2813cf706e52b9da804e/sdk/resourcemanager/eventhub/armeventhub/zz_generated_models.go#L1400)) - however the Swagger isn't describing the element for this field as optional (or in other circumstances, as required) - so I believe this is a separate bug?

Whilst I can understand that this maybe a legacy behaviour, since this is a new API Version (`2021-11-01`) I believe this is both:

1. An API Bug (insofar as the API shouldn't require sending an explicit `null` for each value).
2. A Swagger Bug (insofar as this isn't explicitly marked as Optional/Required).
3. A Go SDK bug (since the element is _assumed_ to be optional, based on 2)

cc @JeffreyRichter @jhendrixMSFT

Contributor guide

Open the contributing guide

Research direction

Start with specification/eventhub/resource-manager/Microsoft.EventHub/stable/2021-11-01/SchemaRegistry.json at lines 255-261, then compare its field definition with the linked generated Go model. Verify the Update API behavior described in the issue and determine which contract and SDK nullability expectations should align. Done means the API specification accurately describes the observed update and value-removal semantics.

Written by the indexing model from the issue text.

Assessment

Tech stack
go, json, openapi
Domain
api
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.