Azure / Azure/azure-rest-api-specs
[EventHub] Swagger doesn't match the API
- 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
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