Improve error response names (#29)

Currently we declare the same 403 response many times over for many endpoints. Just with a unique name for the endpoint. Same for other http status codes.

We did that because for other parts of the code generator, generating unique component refs forced the generator not to be "smart" and re-use things across different endpoints.

However, this is not the case with the error responses.

So DeleteVirtualMachine403Response is actually being used for ~43 different api calls. Not obviously all related to deleting a virtual machine.

Now we name the error response after the errors it returns (excluding the api authenticator ones applied to all responses).

In addition, we don't declare the `oneOf` inside the response, that has been moved to another named schema definition and then referenced from the response. This forces the generator to use the named schema and not try to be "clever".

closes: #28

Author: paulsturgess

lib/apia/open_api/objects/response.rb

@@ -211,13 +211,18 @@ def generate_ref(namespace, http_status_code, definitions)
         end
 
         def generate_id_for_error_ref(http_status_code, definitions)
-          if definitions == api_authenticator_potential_errors.map(&:definition)
+          api_authenticator_error_defs = api_authenticator_potential_errors.map(&:definition).select do |d|
+            d.http_status_code.to_s == http_status_code.to_s
+          end
+          if api_authenticator_error_defs.any? && api_authenticator_error_defs == definitions
             "APIAuthenticator#{http_status_code}Response"
           elsif definitions.length == 1
             "#{generate_id_from_definition(definitions.first)}Response"
           else
             [
-              @route_spec[:operationId].sub(":", "_").gsub(":", "").split("/"),
+              (definitions - api_authenticator_error_defs).map do |d|
+                generate_id_from_definition(d)
+              end.join,
               http_status_code,
               "Response"
             ].flatten.join("_").camelize
@@ -236,7 +241,12 @@ def add_to_responses_components(http_status_code, definitions, id)
             component_schema[:description] = definition.description if definition.description.present?
             schema = generate_schema_properties_for_definition(definition)
           else # the same http status code is used for multiple errors
-            schema = { oneOf: definitions.map { |d| generate_ref("schemas", http_status_code, [d]) } }
+            one_of_id = "OneOf#{id}"
+            @spec[:components][:schemas][one_of_id] = {
+              oneOf: definitions.map { |d| generate_ref("schemas", http_status_code, [d]) }
+            }
+
+            schema = { "$ref": "#/components/schemas/#{one_of_id}" }
           end
 
           component_schema[:content] = {

spec/support/fixtures/openapi.json

@@ -434,7 +434,7 @@
             }
           },
           "400": {
-            "$ref": "#/components/responses/GetTestObject400Response"
+            "$ref": "#/components/responses/InvalidTestAnotherInvalidTest400Response"
           },
           "403": {
             "$ref": "#/components/responses/APIAuthenticator403Response"
@@ -492,7 +492,7 @@
             }
           },
           "400": {
-            "$ref": "#/components/responses/PostTestObject400Response"
+            "$ref": "#/components/responses/InvalidTestAnotherInvalidTest400Response"
           },
           "403": {
             "$ref": "#/components/responses/APIAuthenticator403Response"
@@ -684,6 +684,16 @@
           }
         }
       },
+      "OneOfAPIAuthenticator403Response": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/InvalidTokenResponse"
+          },
+          {
+            "$ref": "#/components/schemas/UnauthorizedNetworkForAPITokenResponse"
+          }
+        ]
+      },
       "RateLimitReached": {
         "type": "object",
         "properties": {
@@ -922,6 +932,16 @@
           }
         }
       },
+      "OneOfInvalidTestAnotherInvalidTest400Response": {
+        "oneOf": [
+          {
+            "$ref": "#/components/schemas/InvalidTestResponse"
+          },
+          {
+            "$ref": "#/components/schemas/AnotherInvalidTestResponse"
+          }
+        ]
+      },
       "ObjectLookup": {
         "description": "All 'object[]' params are mutually exclusive, only one can be provided.",
         "type": "object",
@@ -986,14 +1006,7 @@
         "content": {
           "application/json": {
             "schema": {
-              "oneOf": [
-                {
-                  "$ref": "#/components/schemas/InvalidTokenResponse"
-                },
-                {
-                  "$ref": "#/components/schemas/UnauthorizedNetworkForAPITokenResponse"
-                }
-              ]
+              "$ref": "#/components/schemas/OneOfAPIAuthenticator403Response"
             }
           }
         }
@@ -1044,19 +1057,12 @@
           }
         }
       },
-      "GetTestObject400Response": {
+      "InvalidTestAnotherInvalidTest400Response": {
         "description": "400 error response",
         "content": {
           "application/json": {
             "schema": {
-              "oneOf": [
-                {
-                  "$ref": "#/components/schemas/InvalidTestResponse"
-                },
-                {
-                  "$ref": "#/components/schemas/AnotherInvalidTestResponse"
-                }
-              ]
+              "$ref": "#/components/schemas/OneOfInvalidTestAnotherInvalidTest400Response"
             }
           }
         }
@@ -1083,23 +1089,6 @@
             }
           }
         }
-      },
-      "PostTestObject400Response": {
-        "description": "400 error response",
-        "content": {
-          "application/json": {
-            "schema": {
-              "oneOf": [
-                {
-                  "$ref": "#/components/schemas/InvalidTestResponse"
-                },
-                {
-                  "$ref": "#/components/schemas/AnotherInvalidTestResponse"
-                }
-              ]
-            }
-          }
-        }
       }
     },
     "securitySchemes": {