api_docs: Migrate POST /rest-error-handling.

This commit migrates payload of errors which are common to many endpoints
to /rest-error-handling:post in OpenAPI.

templates/zerver/api/fixtures.json

@@ -1,19 +1,4 @@
 {
-    "invalid-api-key": {
-        "msg": "Invalid API key",
-        "result": "error"
-    },
-    "missing-request-argument-error": {
-        "code": "REQUEST_VARIABLE_MISSING",
-        "msg": "Missing 'content' argument",
-        "result": "error",
-        "var_name": "content"
-    },
-    "user-not-authorized-error": {
-        "code": "BAD_REQUEST",
-        "msg": "User not authorized for this query",
-        "result": "error"
-    },
     "zulip-outgoing-webhook-payload": {
         "data": "@**Outgoing Webhook Test** Zulip is the world\u2019s most productive group chat!",
         "trigger": "mention",

templates/zerver/api/rest-error-handling.md

@@ -21,18 +21,18 @@ errors common to many endpoints:
 
 A typical failed JSON response for when the API key is invalid:
 
-{generate_code_example|invalid-api-key|fixture}
+{generate_code_example|/rest-error-handling:post|fixture(400_invalid_api_key)}
 
 ## Missing request argument(s)
 
 A typical failed JSON response for when a required request argument
 is not supplied:
 
-{generate_code_example|missing-request-argument-error|fixture}
+{generate_code_example|/rest-error-handling:post|fixture(400_missing_request_argument_error)}
 
 ## User not authorized for query
 
 A typical failed JSON response for when the user is not authorized
 for a query:
 
-{generate_code_example|user-not-authorized-error|fixture}
+{generate_code_example|/rest-error-handling:post|fixture(400_user_not_authorized_error)}

zerver/openapi/python_examples.py

@@ -422,8 +422,7 @@ def test_user_not_authorized_error(nonadmin_client):
     # type: (Client) -> None
     result = nonadmin_client.get_streams(include_all_active=True)
 
-    fixture = FIXTURES['user-not-authorized-error']
+    validate_against_openapi_schema(result, '/rest-error-handling', 'post', '400_user_not_authorized_error')
-    test_against_fixture(result, fixture)
 
 def get_subscribers(client):
     # type: (Client) -> None
@@ -1108,15 +1107,14 @@ def update_user_group_members(client, group_id):
 def test_invalid_api_key(client_with_invalid_key):
     # type: (Client) -> None
     result = client_with_invalid_key.list_subscriptions()
-    fixture = FIXTURES['invalid-api-key']
+    validate_against_openapi_schema(result, '/rest-error-handling', 'post', '400_invalid_api_key')
-    test_against_fixture(result, fixture)
 
 def test_missing_request_argument(client):
     # type: (Client) -> None
     result = client.render_message({})
 
-    fixture = FIXTURES['missing-request-argument-error']
+    validate_against_openapi_schema(result, '/rest-error-handling', 'post', '400_missing_request_argument_error')
-    test_against_fixture(result, fixture)
+
 
 def test_invalid_stream_error(client):
     # type: (Client) -> None

zerver/openapi/zulip.yaml

@@ -3260,6 +3260,58 @@ paths:
         default: null
       security:
       - basicAuth: []
+  /rest-error-handling:
+    post:
+      description: |
+        Common error to many endpoints
+      responses:
+        '400_invalid_api_key':
+          description: |
+            Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/JsonError'
+                - example:
+                    {
+                        "msg": "Invalid API key",
+                        "result": "error"
+                    }
+        '400_missing_request_argument_error':
+          description: |
+            Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/CodedError'
+                - properties:
+                    var_name:
+                      type: string
+                      description: |
+                        It contains the information about the missing argument.
+                - example:
+                    {
+                        "code": "REQUEST_VARIABLE_MISSING",
+                        "msg": "Missing 'content' argument",
+                        "result": "error",
+                        "var_name": "content"
+                    }
+        '400_user_not_authorized_error':
+          description: |
+            Bad request.
+          content:
+            application/json:
+              schema:
+                allOf:
+                - $ref: '#/components/schemas/CodedError'
+                - example:
+                    {
+                        "code": "BAD_REQUEST",
+                        "msg": "User not authorized for this query",
+                        "result": "error"
+                    }
 
 components:
   #######################

zerver/tests/test_openapi.py

@@ -203,6 +203,9 @@ class OpenAPIArgumentsTest(ZulipTestCase):
         # Real-time-events endpoint
         '/real-time',
 
+        # Rest error handling endpoint
+        '/rest-error-handling',
+
         #### Mobile-app only endpoints; important for mobile developers.
         # Mobile interface for fetching API keys
         '/fetch_api_key',