openapi: Auto render response descriptions.

This commit modifies the templates to
auto-generate general descriptions of
responses directly from the newly
added field of x-response-description
as a part of the goal of a common template.

templates/zerver/api/add-code-playground.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/realm/playgrounds:post}
 
+{generate_response_description(/realm/playgrounds:post)}
+
 #### Example response
 
 {generate_code_example|/realm/playgrounds:post|fixture(200)}

templates/zerver/api/add-linkifier.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/realm/filters:post}
 
+{generate_response_description(/realm/filters:post)}
+
 #### Example response
 
 {generate_code_example|/realm/filters:post|fixture(200)}

templates/zerver/api/add-reaction.md

@@ -26,6 +26,8 @@
 
 ## Response
 
+{generate_response_description(/messages/{message_id}/reactions:post)}
+
 #### Example response
 
 {generate_code_example|/messages/{message_id}/reactions:post|fixture(200)}

templates/zerver/api/archive-stream.md

@@ -27,6 +27,8 @@
 
 ## Response
 
+{generate_response_description(/streams/{stream_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/streams/{stream_id}:delete|fixture(200)}

templates/zerver/api/check-messages-match-narrow.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/messages/matches_narrow:get}
 
+{generate_response_description(/messages/matches_narrow:get)}
+
 #### Example response
 
 {generate_code_example|/messages/matches_narrow:get|fixture(200)}

templates/zerver/api/create-custom-profile-field.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/realm/profile_fields:post}
 
+{generate_response_description(/realm/profile_fields:post)}
+
 #### Example response
 
 {generate_code_example|/realm/profile_fields:post|fixture(200)}

templates/zerver/api/create-user-group.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/user_groups/create:post)}
+
 #### Example response
 
 {generate_code_example|/user_groups/create:post|fixture(200)}

templates/zerver/api/create-user.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/users:post}
 
+{generate_response_description(/users:post)}
+
 #### Example response
 
 {generate_code_example|/users:post|fixture(200)}

templates/zerver/api/deactivate-own-user.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/me:delete)}
+
 #### Example response
 
 {generate_code_example|/users/me:delete|fixture(200)}

templates/zerver/api/deactivate-user.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/{user_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/users/{user_id}:delete|fixture(200)}

templates/zerver/api/delete-message.md

@@ -27,6 +27,8 @@
 
 ## Response
 
+{generate_response_description(/messages/{message_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/messages/{message_id}:delete|fixture(200)}

templates/zerver/api/delete-queue.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/events:delete)}
+
 #### Example response
 
 {generate_code_example|/events:delete|fixture(200)}

templates/zerver/api/dev-fetch-api-key.md

@@ -21,6 +21,8 @@
 
 {generate_return_values_table|zulip.yaml|/dev_fetch_api_key:post}
 
+{generate_response_description(/dev_fetch_api_key:post)}
+
 #### Example response
 
 {generate_code_example|/dev_fetch_api_key:post|fixture(200)}

templates/zerver/api/get-attachments.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/attachments:get}
 
+{generate_response_description(/attachments:get)}
+
 #### Example response
 
 {generate_code_example|/attachments:get|fixture(200)}

templates/zerver/api/get-custom-emoji.md

@@ -28,6 +28,8 @@
 {generate_return_values_table|zulip.yaml|/realm/emoji:get}
 
 
+{generate_response_description(/realm/emoji:get)}
+
 #### Example response
 
 {generate_code_example|/realm/emoji:get|fixture(200)}

templates/zerver/api/get-custom-profile-fields.md

@@ -28,6 +28,8 @@
 {generate_return_values_table|zulip.yaml|/realm/profile_fields:get}
 
 
+{generate_response_description(/realm/profile_fields:get)}
+
 #### Example response
 
 {generate_code_example|/realm/profile_fields:get|fixture(200)}

templates/zerver/api/get-events.md

@@ -51,6 +51,8 @@ endpoint and a queue would be registered in the absence of a `queue_id`.
 
 {generate_return_values_table|zulip.yaml|/events:get}
 
+{generate_response_description(/events:get)}
+
 #### Example response
 
 {generate_code_example|/events:get|fixture(200)}

templates/zerver/api/get-linkifiers.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/realm/linkifiers:get}
 
+{generate_response_description(/realm/linkifiers:get)}
+
 #### Example response
 
 {generate_code_example|/realm/linkifiers:get|fixture(200)}

templates/zerver/api/get-message-history.md

@@ -37,6 +37,8 @@ will only contain data for the modified fields (e.g. if only the topic
 was edited, `prev_content`, `prev_rendered_content`, and
 `content_html_diff` will not appear).
 
+{generate_response_description(/messages/{message_id}/history:get)}
+
 #### Example response
 
 {generate_code_example|/messages/{message_id}/history:get|fixture(200)}

templates/zerver/api/get-messages.md

@@ -31,6 +31,8 @@ present in all Zulip API responses).
 
 {generate_return_values_table|zulip.yaml|/messages:get}
 
+{generate_response_description(/messages:get)}
+
 #### Example response
 
 {generate_code_example|/messages:get|fixture(200)}

templates/zerver/api/get-own-user.md

@@ -27,6 +27,8 @@ This endpoint takes no parameters.
 
 {generate_return_values_table|zulip.yaml|/users/me:get}
 
+{generate_response_description(/users/me:get)}
+
 #### Example response
 
 {generate_code_example|/users/me:get|fixture(200)}

templates/zerver/api/get-raw-message.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/messages/{message_id}:get}
 
+{generate_response_description(/messages/{message_id}:get)}
+
 #### Example response
 
 {generate_code_example|/messages/{message_id}:get|fixture(200)}

templates/zerver/api/get-server-settings.md

@@ -39,6 +39,8 @@ response, for two reasons:
   multi-subdomain server, like the root domain of zulip.com, the settings
   that are realm-specific are not known and thus not provided.
 
+{generate_response_description(/server_settings:get)}
+
 #### Example response
 
 {generate_code_example|/server_settings:get|fixture(200)}

templates/zerver/api/get-stream-id.md

@@ -29,6 +29,8 @@
 
 {generate_return_values_table|zulip.yaml|/get_stream_id:get}
 
+{generate_response_description(/get_stream_id:get)}
+
 #### Example response
 
 {generate_code_example|/get_stream_id:get|fixture(200)}

templates/zerver/api/get-stream-topics.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/users/me/{stream_id}/topics:get}
 
+{generate_response_description(/users/me/{stream_id}/topics:get)}
+
 #### Example response
 
 {generate_code_example|/users/me/{stream_id}/topics:get|fixture(200)}

templates/zerver/api/get-streams.md

@@ -29,6 +29,8 @@
 
 {generate_return_values_table|zulip.yaml|/streams:get}
 
+{generate_response_description(/streams:get)}
+
 #### Example response
 
 {generate_code_example|/streams:get|fixture(200)}

templates/zerver/api/get-subscription-status.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/{user_id}/subscriptions/{stream_id}:get)}
+
 #### Example response
 
 {generate_code_example|/users/{user_id}/subscriptions/{stream_id}:get|fixture(200)}

templates/zerver/api/get-subscriptions.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions:get}
 
+{generate_response_description(/users/me/subscriptions:get)}
+
 #### Example response
 
 {generate_code_example|/users/me/subscriptions:get|fixture(200)}

templates/zerver/api/get-user-by-email.md

@@ -29,6 +29,8 @@
 
 {generate_return_values_table|zulip.yaml}|/users/{email}:get}
 
+{generate_response_description(/users/{email}:get)}
+
 #### Example response
 
 {generate_code_example|/users/{email}:get|fixture(200)}

templates/zerver/api/get-user-groups.md

@@ -29,6 +29,8 @@
 
 {generate_return_values_table|zulip.yaml|/user_groups:get}
 
+{generate_response_description(/user_groups:get)}
+
 #### Example response
 
 {generate_code_example|/user_groups:get|fixture(200)}

templates/zerver/api/get-user-presence.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/users/{user_id_or_email}/presence:get}
 
+{generate_response_description(/users/{user_id_or_email}/presence:get)}
+
 #### Example response
 
 {generate_code_example|/users/{user_id_or_email}/presence:get|fixture(200)}

templates/zerver/api/get-user.md

@@ -29,6 +29,8 @@
 
 {generate_return_values_table|zulip.yaml}|/users/{user_id}:get}
 
+{generate_response_description(/users/{user_id}:get)}
+
 #### Example response
 
 {generate_code_example|/users/{user_id}:get|fixture(200)}

templates/zerver/api/get-users.md

@@ -29,6 +29,8 @@
 
 {generate_return_values_table|zulip.yaml|/users:get}
 
+{generate_response_description(/users:get)}
+
 #### Example response
 
 {generate_code_example|/users:get|fixture(200)}

templates/zerver/api/mark-all-as-read.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/mark_all_as_read:post)}
+
 #### Example response
 
 {generate_code_example|/mark_all_as_read:post|fixture(200)}
@@ -60,6 +62,8 @@
 
 ## Response
 
+{generate_response_description(/mark_all_as_read:post)}
+
 #### Example response
 
 {generate_code_example|/mark_stream_as_read:post|fixture(200)}
@@ -96,6 +100,8 @@
 
 ## Response
 
+{generate_response_description(/mark_all_as_read:post)}
+
 #### Example response
 
 {generate_code_example|/mark_topic_as_read:post|fixture(200)}

templates/zerver/api/mute-topic.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/me/subscriptions/muted_topics:patch)}
+
 #### Example response
 
 {generate_code_example|/users/me/subscriptions/muted_topics:patch|fixture(200)}

templates/zerver/api/mute-user.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/me/muted_users/{muted_user_id}:post)}
+
 #### Example response
 
 {generate_code_example|/users/me/muted_users/{muted_user_id}:post|fixture(200)}

templates/zerver/api/reactivate-user.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/{user_id}/reactivate:post)}
+
 #### Example response
 
 {generate_code_example|/users/{user_id}/reactivate:post|fixture(200)}

templates/zerver/api/remove-code-playground.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/realm/playgrounds/{playground_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/realm/playgrounds/{playground_id}:delete|fixture(200)}

templates/zerver/api/remove-linkifier.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/realm/filters/{filter_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/realm/filters/{filter_id}:delete|fixture(200)}

templates/zerver/api/remove-reaction.md

@@ -27,6 +27,8 @@
 
 ## Response
 
+{generate_response_description(/messages/{message_id}/reactions:delete)}
+
 #### Example response
 
 {generate_code_example|/messages/{message_id}/reactions:delete|fixture(200)}

templates/zerver/api/remove-user-group.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/user_groups/{user_group_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/user_groups/{user_group_id}:delete|fixture(200)}

templates/zerver/api/render-message.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/messages/render:post}
 
+{generate_response_description(/messages/render:post)}
+
 #### Example response
 
 {generate_code_example|/messages/render:post|fixture(200)}

templates/zerver/api/reorder-custom-profile-fields.md

@@ -28,6 +28,8 @@
 {generate_return_values_table|zulip.yaml|/realm/profile_fields:patch}
 
 
+{generate_response_description(/realm/profile_fields:patch)}
+
 #### Example response
 
 {generate_code_example|/realm/profile_fields:patch|fixture(200)}

templates/zerver/api/send-message.md

@@ -73,6 +73,8 @@ file.
 
 {generate_return_values_table|zulip.yaml|/messages:post}
 
+{generate_response_description(/messages:post)}
+
 #### Example response
 
 {generate_code_example|/messages:post|fixture(200)}

templates/zerver/api/set-typing-status.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/typing:post)}
+
 #### Example response
 
 {generate_code_example|/typing:post|fixture(200)}

templates/zerver/api/subscribe.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions:post}
 
+{generate_response_description(/users/me/subscriptions:post)}
+
 #### Example response
 
 {generate_code_example|/users/me/subscriptions:post|fixture(200)}

templates/zerver/api/unmute-user.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/me/muted_users/{muted_user_id}:delete)}
+
 #### Example response
 
 {generate_code_example|/users/me/muted_users/{muted_user_id}:delete|fixture(200)}

templates/zerver/api/unsubscribe.md

@@ -23,6 +23,8 @@
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions:delete}
 
+{generate_response_description(/users/me/subscriptions:delete)}
+
 #### Example response
 
 {generate_code_example|/users/me/subscriptions:delete|fixture(200)}

templates/zerver/api/update-display-settings.md

@@ -32,6 +32,8 @@ with their new value. Please note that this doesn't necessarily mean that it
 will return all the settings passed as parameters in the request, but only
 those ones that were different from the already existing setting.
 
+{generate_response_description(/settings/display:patch)}
+
 #### Example response
 
 {generate_code_example|/settings/display:patch|fixture(200)}

templates/zerver/api/update-linkifier.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/realm/filters/{filter_id}:patch}
 
+{generate_response_description(/realm/filters/{filter_id}:patch)}
+
 #### Example response
 
 {generate_code_example|/realm/filters/{filter_id}:patch|fixture(200)}

templates/zerver/api/update-message-flags.md

@@ -99,6 +99,8 @@
 
 {generate_return_values_table|zulip.yaml|/messages/flags:post}
 
+{generate_response_description(/messages/flags:post)}
+
 #### Example response
 
 {generate_code_example|/messages/flags:post|fixture(200)}

templates/zerver/api/update-message.md

@@ -34,6 +34,8 @@ You only have permission to edit a message if:
 
 ## Response
 
+{generate_response_description(/messages/{message_id}:patch)}
+
 #### Example response
 
 {generate_code_example|/messages/{message_id}:patch|fixture(200)}

templates/zerver/api/update-notification-settings.md

@@ -32,6 +32,8 @@ with their new value. Please note that this doesn't necessarily mean that it
 will return all the settings passed as parameters in the request, but only
 those ones that were different than the already existing setting.
 
+{generate_response_description(/settings/notifications:patch)}
+
 #### Example response
 
 {generate_code_example|/settings/notifications:patch|fixture(200)}

templates/zerver/api/update-stream.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/streams/{stream_id}:patch)}
+
 #### Example response
 
 {generate_code_example|/streams/{stream_id}:patch|fixture(200)}

templates/zerver/api/update-subscription-settings.md

@@ -27,6 +27,8 @@
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions/properties:post}
 
+{generate_response_description(/users/me/subscriptions/properties:post)}
+
 #### Example response
 
 {generate_code_example|/users/me/subscriptions/properties:post|fixture(200)}

templates/zerver/api/update-user-group-members.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/user_groups/{user_group_id}/members:post)}
+
 #### Example response
 
 {generate_code_example|/user_groups/{user_group_id}/members:post|fixture(200)}

templates/zerver/api/update-user-group.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/user_groups/{user_group_id}:patch)}
+
 #### Example response
 
 {generate_code_example|/user_groups/{user_group_id}:patch|fixture(200)}

templates/zerver/api/update-user.md

@@ -25,6 +25,8 @@
 
 ## Response
 
+{generate_response_description(/users/{user_id}:patch)}
+
 #### Example response
 
 {generate_code_example|/users/{user_id}:patch|fixture(200)}

templates/zerver/api/upload-custom-emoji.md

@@ -41,6 +41,8 @@ to 5MB.
 [1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
 {generate_parameter_description(/realm/emoji/{emoji_name}:post)}
 
+
+{generate_response_description(/realm/emoji/{emoji_name}:post)}
 ## Response
 #### Example response
 

templates/zerver/api/upload-file.md

@@ -37,6 +37,8 @@ to 25MB.
 
 {generate_return_values_table|zulip.yaml|/user_uploads:post}
 
+{generate_response_description(/user_uploads:post)}
+
 #### Example response
 
 {generate_code_example|/user_uploads:post|fixture(200)}