Missing Error Definitions or References in 9 Swagger Specs

[selvasingh]

Missing Error Definitions or References in 9 Swagger Specs

• Data Lake Catalog
• DNS
• Graph RBAC
• Logic
• Notification Hubs
• Resources Features
• Resources Lock
• Search
• Service Fabric

Notification Hubs REST API throws several error codes however its Swagger does not define any of these.

Search REST API throws several error codes however its Swagger does not define any of these.

Azure Active Directory Graph API throws several error codes however its Swagger does not define any of these.

So on and on ...

[devigned]

Which error codes are you referring to? Please be specific or the issues will be long lived and difficult to determine if they are completely resolved.

[selvasingh]

@devigned - if you go to their corresponding REST API specs, then you can see it. I provided some examples in the first comment

[devigned]

@Azure/adx-autorest-contributors and @Azure/openapi-advisors any thoughts on this issue?

[brjohnstmsft]

@devigned Two thoughts, one specific to Search, one general:

1. The Search Swagger specs are not what I would call "production-ready" yet. We have an issue open to decide what to do about this: OpenAPI specs that are not complete should not be in master #195 It would be great to close on it so we can be omitted from these sweeps until we are ready.
2. From a codegen standpoint, would adding the additional error codes change anything? For example, in C#, AutoRest basically assumes that success means return a response, while failure means throw a CloudException. I'm confident we have already captured all the success cases in the Search specs. Other than for documentation purposes, is there any value in explicitly enumerating all the possible failure cases in the specs?

[devigned]

OAI/OpenAPI-Specification#566 <-- to help follow 3.0 suggestions

[devigned]

We should have a shared (common) set of schema, a base error should be returned by default (non-success responses) specialized by the error code via a polymorphic discriminator. This will provide the information to specialize the initialized class as well as the to document all of the possible error responses.

[kirthik]

Closing since this is being tracked here - Azure/autorest#1523.