api-docs: Document bulk mark as read endpoints as deprecated. #27349
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
laurynmm
added
area: documentation (api and integrations)
api docs review
|
Hello @zulip/server-api members, this pull request was labeled with the "area: documentation (api and integrations)" label, so you may want to check it out! |
timabbott
reviewed
Oct 24, 2023
|
LGTM modulo Tim's comments above. Thanks @laurynmm for this cleanup! |
Previously, we had checked that deprecated parameters and return values had been marked as `deprecated: true` in the OpenAPI documentation and had a description with a deprecated note. Here we extend that check at the top level to deprecated endpoints. The backend test that catches a failed assertion for this check is `test_api_doc_endpoints` in zerver/tests/test_docs.py as that test checks for a success response all pages linked the sidebar of the API documentation.
laurynmm
force-pushed
the
api-docs-deprecate-bulk-mark-as-read-endpoints
branch
from
4c37306
to
a9805d9
Compare
|
Updates:
A follow-up to these changes may be to add a stronger visual indication that the endpoint is deprecated in the rendered documentation. For example, here's the deprecated use_first_unread_anchor parameter in get-messages: https://zulip.com/api/get-messages#parameter-use_first_unread_anchor. |
|
Merged, thanks @laurynmm! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adds a deprecated changes note to the three bulk mark as read endpoints in the API documentation and removes the out of date link/reference to the bulk mark messages as read endpoints in the main description for the update personal message flags endpoint.
See CZO discussion.
Part of work on #23598.
Screenshots and screen captures:
Mark messages in topic as read endpoint main description
Current documentation
Mark messages in stream as read endpoint main description
Current documentation
Mark all as read endpoint main description
Current documentation
Self-review checklist
(variable names, code reuse, readability, etc.).
Communicate decisions, questions, and potential concerns.
Individual commits are ready for review (see commit discipline).
Completed manual review and testing of the following: