search

Azure / azure-rest-api-specs

The source for REST API specifications for Microsoft Azure.
MIT License
2.61k stars 5.03k forks source link

[EventGrid] Swagger ModelValidation INVALID_TYPE #25381

Open mikeharder opened 1 year ago

mikeharder commented 1 year ago

Check Swagger ModelValidation is failing on EventGrid with this error:

##[error]Validating "examples" and "x-ms-examples" in  specification/eventgrid/data-plane/Microsoft.EventGrid/preview/2023-06-01-preview/EventGrid.json:
 error : 
code: INVALID_TYPE
message: Expected type  but found type object
schemaUrl: >-
  specification/eventgrid/data-plane/Microsoft.EventGrid/preview/2023-06-01-preview/EventGrid.json
exampleUrl: >-
  specification/eventgrid/data-plane/Microsoft.EventGrid/preview/2023-06-01-preview/examples/publish.json
schemaPosition:
  line: 82
  column: 22
schemaJsonPath: !<tag:yaml.org,2002:js/undefined> ''
examplePosition:
  line: 24
  column: 16
exampleJsonPath: $response.200/body
severity: 0
source: response
operationId: PublishCloudEvents
level: error

https://github.com/Azure/azure-rest-api-specs/pull/25323/checks?check_run_id=15930723858

From @johanste:

It looks to me like validation of examples of APIs that return an empty object may be incorrect. There is (or at least was) some ambiguity between not returning anything and returning an empty object in x-ms-examples. For the longest time it didn't matter, but at some point it was decided by the REST API review board that returning nothing was bad and empty object preferred.

I believe this behavior is coded here:

https://github.com/Azure/oav/blob/760a3352a04ebfcd2e9a1d05c7ad4925f20caa2c/lib/swaggerValidator/modelValidator.ts#L744

l0lawrence commented 1 year ago

25387

mikeharder commented 1 year ago

25387

Attempted fix, rejected until we better understand the issue.

mikeharder commented 1 year ago

I searched for similar specs in the repo, and what I found was interesting. Here is the swagger and example for Cdn@2017-10-12:

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/cdn/resource-manager/Microsoft.Cdn/stable/2017-10-12/cdn.json#L1562-L1565

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/cdn/resource-manager/Microsoft.Cdn/stable/2017-10-12/examples/CustomDomains_Delete.json#L10-L14

In Cdn@2019-04-15, the swagger is unchanged, but the example response is changed from "200": { "body": { } } to "200": { }:

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/cdn/resource-manager/Microsoft.Cdn/stable/2019-04-15/cdn.json#L1562-L1565

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/cdn/resource-manager/Microsoft.Cdn/stable/2019-04-15/examples/CustomDomains_Delete.json#L10-L12

Here are the swagger and example for EventGrid@2023-06-01:

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/eventgrid/data-plane/Microsoft.EventGrid/preview/2023-06-01-preview/EventGrid.json#L82-L88

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/eventgrid/data-plane/Microsoft.EventGrid/preview/2023-06-01-preview/EventGrid.json#L554-L558

https://github.com/Azure/azure-rest-api-specs/blob/1d2b8c05b55be5dd98ce94c835d7e96ee1ea7f5d/specification/eventgrid/data-plane/Microsoft.EventGrid/preview/2023-06-01-preview/examples/publish.json#L24-L28

@johanste, @l0lawrence: Given these examples, do you still think check Swagger ModelValidation is reporting a false positive for EventGrid? Meaning Swagger ModelValidation should be updated so the above EventGrid swagger and example is not a violation?

Or perhaps the EventGrid example should be changed from "200": { "body": { } } to "200": { }, like how the Cdn sample was changed between the two versions?