openapi: Auto render parameter descriptions.

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

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/playgrounds:post}
 
+{generate_parameter_description(/realm/playgrounds:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/playgrounds:post}

templates/zerver/api/add-linkifier.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/filters:post}
 
+{generate_parameter_description(/realm/filters:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/filters:post}

templates/zerver/api/add-reaction.md

@@ -22,6 +22,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/{message_id}/reactions:post}
 
+{generate_parameter_description(/messages/{message_id}/reactions:post)}
+
 ## Response
 
 #### Example response

templates/zerver/api/archive-stream.md

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/streams/{stream_id}:delete}
 
+{generate_parameter_description(/streams/{stream_id}:delete)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/matches_narrow:get}
 
+{generate_parameter_description(/messages/matches_narrow:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/messages/matches_narrow:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/profile_fields:post}
 
+{generate_parameter_description(/realm/profile_fields:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/profile_fields:post}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/user_groups/create:post}
 
+{generate_parameter_description(/user_groups/create:post)}
+
 ## Response
 
 #### Example response

templates/zerver/api/create-user.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users:post}
 
+{generate_parameter_description(/users:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users:post}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me:delete}
 
+{generate_parameter_description(/users/me:delete)}
+
 ## Response
 
 #### Example response

templates/zerver/api/deactivate-user.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{user_id}:delete}
 
+{generate_parameter_description(/users/{user_id}:delete)}
+
 ## Response
 
 #### Example response

templates/zerver/api/delete-message.md

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/{message_id}:delete}
 
+{generate_parameter_description(/messages/{message_id}:delete)}
+
 ## Response
 
 #### Example response

templates/zerver/api/delete-queue.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/events:delete}
 
+{generate_parameter_description(/events:delete)}
+
 ## Response
 
 #### Example response

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

@@ -15,6 +15,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/dev_fetch_api_key:post}
 
+{generate_parameter_description(/dev_fetch_api_key:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/dev_fetch_api_key:post}

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

@@ -15,6 +15,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/fetch_api_key:post}
 
+{generate_parameter_description(/fetch_api_key:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/fetch_api_key:post}

templates/zerver/api/get-attachments.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/attachments:get}
 
+{generate_parameter_description(/attachments:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/attachments:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/emoji:get}
 
+{generate_parameter_description(/realm/emoji:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/emoji:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/profile_fields:get}
 
+{generate_parameter_description(/realm/profile_fields:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/profile_fields:get}

templates/zerver/api/get-events.md

@@ -45,6 +45,7 @@ even if you haven't registered a queue by explicitly requesting the
 `{{ api_url}}/v1/register` endpoint, you could pass the parameters for
 [the `{{ api_url}}/v1/register` endpoint](/api/register-queue) to this
 endpoint and a queue would be registered in the absence of a `queue_id`.
+{generate_parameter_description(/events:get)}
 
 ## Response
 

templates/zerver/api/get-linkifiers.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/linkifiers:get}
 
+{generate_parameter_description(/realm/linkifiers:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/linkifiers:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/{message_id}/history:get}
 
+{generate_parameter_description(/messages/{message_id}/history:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/messages/{message_id}/history:get}

templates/zerver/api/get-messages.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages:get}
 
+{generate_parameter_description(/messages:get)}
+
 ## Response
 
 When a request is successful, this endpoint returns a dictionary

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

@@ -21,6 +21,8 @@
 
 This endpoint takes no parameters.
 
+{generate_parameter_description(/users/me:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users/me:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/{message_id}:get}
 
+{generate_parameter_description(/messages/{message_id}:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/messages/{message_id}:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/server_settings:get}
 
+{generate_parameter_description(/server_settings:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/server_settings:get}

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

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/get_stream_id:get}
 
+{generate_parameter_description(/get_stream_id:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/get_stream_id:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/{stream_id}/topics:get}
 
+{generate_parameter_description(/users/me/{stream_id}/topics:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users/me/{stream_id}/topics:get}

templates/zerver/api/get-streams.md

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/streams:get}
 
+{generate_parameter_description(/streams:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/streams:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{user_id}/subscriptions/{stream_id}:get}
 
+{generate_parameter_description(/users/{user_id}/subscriptions/{stream_id}:get)}
+
 ## Response
 
 #### Example response

templates/zerver/api/get-subscriptions.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/subscriptions:get}
 
+{generate_parameter_description(/users/me/subscriptions:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions:get}

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

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{email}:get}
 
+{generate_parameter_description(/users/{email}:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml}|/users/{email}:get}

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

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/user_groups:get}
 
+{generate_parameter_description(/user_groups:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/user_groups:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{user_id_or_email}/presence:get}
 
+{generate_parameter_description(/users/{user_id_or_email}/presence:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users/{user_id_or_email}/presence:get}

templates/zerver/api/get-user.md

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{user_id}:get}
 
+{generate_parameter_description(/users/{user_id}:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml}|/users/{user_id}:get}

templates/zerver/api/get-users.md

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users:get}
 
+{generate_parameter_description(/users:get)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users:get}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/mark_all_as_read:post}
 
+{generate_parameter_description(/mark_all_as_read:post)}
+
 ## Response
 
 #### Example response
@@ -54,6 +56,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/mark_stream_as_read:post}
 
+{generate_parameter_description(/mark_all_as_read:post)}
+
 ## Response
 
 #### Example response
@@ -88,6 +92,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/mark_topic_as_read:post}
 
+{generate_parameter_description(/mark_all_as_read:post)}
+
 ## Response
 
 #### Example response

templates/zerver/api/mute-topic.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/subscriptions/muted_topics:patch}
 
+{generate_parameter_description(/users/me/subscriptions/muted_topics:patch)}
+
 ## Response
 
 #### Example response

templates/zerver/api/mute-user.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/muted_users/{muted_user_id}:post}
 
+{generate_parameter_description(/users/me/muted_users/{muted_user_id}:post)}
+
 ## Response
 
 #### Example response

templates/zerver/api/reactivate-user.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{user_id}/reactivate:post}
 
+{generate_parameter_description(/users/{user_id}/reactivate:post)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/playgrounds/{playground_id}:delete}
 
+{generate_parameter_description(/realm/playgrounds/{playground_id}:delete)}
+
 ## Response
 
 #### Example response

templates/zerver/api/remove-linkifier.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/filters/{filter_id}:delete}
 
+{generate_parameter_description(/realm/filters/{filter_id}:delete)}
+
 ## Response
 
 #### Example response

templates/zerver/api/remove-reaction.md

@@ -23,6 +23,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/{message_id}/reactions:delete}
 
+{generate_parameter_description(/messages/{message_id}/reactions:delete)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/user_groups/{user_group_id}:delete}
 
+{generate_parameter_description(/user_groups/{user_group_id}:delete)}
+
 ## Response
 
 #### Example response

templates/zerver/api/render-message.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/messages/render:post}
 
+{generate_parameter_description(/messages/render:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/messages/render:post}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/profile_fields:patch}
 
+{generate_parameter_description(/realm/profile_fields:patch)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/profile_fields:patch}

templates/zerver/api/send-message.md

@@ -67,6 +67,8 @@ file.
 
 {generate_api_arguments_table|zulip.yaml|/messages:post}
 
+{generate_parameter_description(/messages:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/messages:post}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/typing:post}
 
+{generate_parameter_description(/typing:post)}
+
 ## Response
 
 #### Example response

templates/zerver/api/subscribe.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/subscriptions:post}
 
+{generate_parameter_description(/users/me/subscriptions:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions:post}

templates/zerver/api/unmute-user.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/muted_users/{muted_user_id}:delete}
 
+{generate_parameter_description(/users/me/muted_users/{muted_user_id}:delete)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/settings/display:patch}
 
+{generate_parameter_description(/settings/display:patch)}
+
 ## Response
 
 #### Return values

templates/zerver/api/update-linkifier.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/realm/filters/{filter_id}:patch}
 
+{generate_parameter_description(/realm/filters/{filter_id}:patch)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/realm/filters/{filter_id}:patch}

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

@@ -93,6 +93,7 @@
         </tbody>
     </table>
 </div>
+{generate_parameter_description(/messages/flags:post)}
 
 ## Response
 

templates/zerver/api/update-message.md

@@ -30,6 +30,8 @@ You only have permission to edit a message if:
 
 {generate_api_arguments_table|zulip.yaml|/messages/{message_id}:patch}
 
+{generate_parameter_description(/messages/{message_id}:patch)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/settings/notifications:patch}
 
+{generate_parameter_description(/settings/notifications:patch)}
+
 ## Response
 
 #### Return values

templates/zerver/api/update-stream.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/streams/{stream_id}:patch}
 
+{generate_parameter_description(/streams/{stream_id}:patch)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/me/subscriptions/properties:post}
 
+{generate_parameter_description(/users/me/subscriptions/properties:post)}
+
 ## Response
 
 {generate_return_values_table|zulip.yaml|/users/me/subscriptions/properties:post}

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/user_groups/{user_group_id}/members:post}
 
+{generate_parameter_description(/user_groups/{user_group_id}/members:post)}
+
 ## Response
 
 #### Example response

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

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/user_groups/{user_group_id}:patch}
 
+{generate_parameter_description(/user_groups/{user_group_id}:patch)}
+
 ## Response
 
 #### Example response

templates/zerver/api/update-user.md

@@ -21,6 +21,8 @@
 
 {generate_api_arguments_table|zulip.yaml|/users/{user_id}:patch}
 
+{generate_parameter_description(/users/{user_id}:patch)}
+
 ## Response
 
 #### Example response

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

@@ -39,6 +39,7 @@ in the [server's settings][1]. `MAX_EMOJI_FILE_SIZE_MIB` defaults
 to 5MB.
 
 [1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
+{generate_parameter_description(/realm/emoji/{emoji_name}:post)}
 
 ## Response
 #### Example response

templates/zerver/api/upload-file.md

@@ -31,6 +31,7 @@ in the [server's settings][1]. `MAX_FILE_UPLOAD_SIZE` defaults
 to 25MB.
 
 [1]: https://zulip.readthedocs.io/en/latest/subsystems/settings.html#server-settings
+{generate_parameter_description(/user_uploads:post)}
 
 ## Response