Requirement to model errors as "default" makes it hard to document error cases

Currently, AutoRest expects that all responses that aren’t “default” in the Swagger spec are success cases. However, this makes it difficult to document error cases.

For example, in order to have AutoRest generate the correct code, I need to do this:

"responses": {
  "200": {
    "description": "Description of a successful response.",
    "schema": {
      "$ref": "#/definitions/AdminKeyResult"
    }
  },
  "default": {
    "description": "HTTP 404: The subscription, resource group, or Search service could not be found. HTTP 409: The specified subscription is disabled.",
    "schema": {
      "$ref": "#/definitions/CloudError"
    }
  }
}

But what I want to do is something like this:

"responses": {
  "200": {
    "description": "Description of a successful response.",
    "schema": {
      "$ref": "#/definitions/AdminKeyResult"
    }
  },
  "404": {
    "description": "The subscription, resource group, or Search service could not be found.",
    "schema": {
      "$ref": "#/definitions/CloudError"
    }
  },
  "409": {
    "description": "The specified subscription is disabled.",
    "schema": {
      "$ref": "#/definitions/CloudError"
    }
  },
  "default": {
    "description": "An unexpected error occurred.",
    "schema": {
      "$ref": "#/definitions/CloudError"
    }
  }
}

Where perhaps AutoRest can tell a response case is an error by the presence of an error contract (#/definitions/CloudError).

This is important because as Azure reference documentation moves to docs.microsoft.com, we are moving towards auto-generated REST API reference docs that are sourced from the same Swagger specs that we use to generate SDKs. These two processes/toolchains (docs via DocFX/docs.microsoft.com and SDK code via AutoRest) need to work well together.

[csteegz]

I have a pair of proposals/branches to address this - I believe they’re pretty close to being ready for a PR if either are wanted, but I’m sure there is a lot of discussion to be have about this - I could also open PRs if that is a better way to facilitate discussion.

These proposals are both predicated on two ideas: 1. There is a canonical error response model for a specific web service. 2. This canonical error response is specified by the default tag in the swagger.

This is in line with how autorest currently treats errors, although it does limit the behavior in regards to inheritance as Thomas discuses above. That being said, it is pretty extensible as it allows different error responses for different routes, and services.

Following these ideas is easier for implementation because we don’t have to change anything in actual code generation - we just have to modify the modeler to “ignore” certain responses (This does mean that the autorest modeler wouldn’t be able to be used to generate static docs). Anything that doesn’t follow both of these would require more work - I believe that the responses would need a way to indicate that they are errors and each code generator would need to be modified to treat those errors accordingly.

x-ms-treat-as-default

My first proposal is the simple and obvious ones - we add an extension field x-ms-treat-as-default to response that tells the modeler to ignore that response, which means that it gets treated as a response. This is simple, explicit in the swagger and newer versions of Autorest will generate the same code when run against older swagger versions. The disadvantage is that this requires extra work for the person who writes the swagger and feels unintuitive - I don’t know if this should be a vendor extension, it feels like core behavior.

Treat default type as error

My second proposal is basically just an implementation of what Bruce proposed above - if a response has the same schema as the default, it is treated as an error. To me, this feels like the way that the codegen should work. This has the obvious downside of limiting the models the user can use - but, since my implementation uses the name, the user could just create an identical non-error model.

I’d love for anyone to take a look at these two proposals, if either of them seem reasonable I can open a PR. I think both of these proposals address the constraints previously mentioned in this issue.

[fearthecowboy]

Added to the vNext generator support.