From d62b75fc4c3c032b588a3759d8a5fbedc223b5cd Mon Sep 17 00:00:00 2001 From: "Hemanth V. Alluri" Date: Fri, 19 Jul 2019 10:32:10 +0530 Subject: [PATCH] openapi: Remove /users/me/subscriptions from pending_endpoints. In commit 7c71e98, we added a special exception for the /users/me/subscriptions endpoint in the automatic validation test. By adding some extra documentation, we now remove this extra code, as well as the endpoint from the list of pending endpoints. --- templates/zerver/api/fixtures.json | 83 ------------ .../zerver/api/get-subscribed-streams.md | 4 +- zerver/lib/api_test_helpers.py | 7 +- zerver/openapi/zulip.yaml | 125 ++++++++++++++++++ zerver/tests/test_openapi.py | 13 +- 5 files changed, 131 insertions(+), 101 deletions(-) diff --git a/templates/zerver/api/fixtures.json b/templates/zerver/api/fixtures.json index b26d333f40..75b659f8bd 100644 --- a/templates/zerver/api/fixtures.json +++ b/templates/zerver/api/fixtures.json @@ -18,89 +18,6 @@ "short_name": "iago", "user_id": 5 }, - "get-subscribed-streams": { - "msg": "", - "result": "success", - "subscriptions": [ - { - "audible_notifications": true, - "color": "#e79ab5", - "description": "A Scandinavian country", - "desktop_notifications": true, - "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981", - "in_home_view": true, - "invite_only": false, - "name": "Denmark", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 1, - "subscribers": [ - "ZOE@zulip.com", - "hamlet@zulip.com", - "iago@zulip.com", - "othello@zulip.com", - "prospero@zulip.com" - ] - }, - { - "audible_notifications": true, - "color": "#e79ab5", - "description": "Located in the United Kingdom", - "desktop_notifications": true, - "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981", - "in_home_view": true, - "invite_only": false, - "name": "Scotland", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 3, - "subscribers": [ - "ZOE@zulip.com", - "iago@zulip.com", - "othello@zulip.com", - "prospero@zulip.com" - ] - }, - { - "audible_notifications": true, - "color": "#e79ab5", - "description": "A city in Italy", - "desktop_notifications": true, - "email_address": "Verona+faaa92dc82cf143174ddc098a1c832ef@zulipdev.com:9981", - "in_home_view": true, - "invite_only": false, - "name": "Verona", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 5, - "subscribers": [ - "AARON@zulip.com", - "ZOE@zulip.com", - "cordelia@zulip.com", - "hamlet@zulip.com", - "iago@zulip.com", - "othello@zulip.com", - "prospero@zulip.com" - ] - }, - { - "audible_notifications": false, - "color": "#76ce90", - "description": "New stream for testing", - "desktop_notifications": false, - "email_address": "new%0032stream+e1917b4fc733268e91fcc57cf79a9249@zulipdev.com:9981", - "in_home_view": true, - "invite_only": false, - "name": "new stream", - "pin_to_top": false, - "push_notifications": false, - "stream_id": 6, - "subscribers": [ - "iago@zulip.com" - ] - } - ] - }, "invalid-api-key": { "msg": "Invalid API key", "result": "error" diff --git a/templates/zerver/api/get-subscribed-streams.md b/templates/zerver/api/get-subscribed-streams.md index 87600667b0..6d9335c481 100644 --- a/templates/zerver/api/get-subscribed-streams.md +++ b/templates/zerver/api/get-subscribed-streams.md @@ -9,7 +9,7 @@ Get all streams that the user is subscribed to. {start_tabs} {tab|python} -{generate_code_example(python)|get-subscribed-streams|example} +{generate_code_example(python)|/users/me/subscriptions:get|example} {tab|js} @@ -74,4 +74,4 @@ This request takes no arguments. A typical successful JSON response may look like: -{generate_code_example|get-subscribed-streams|fixture} +{generate_code_example|/users/me/subscriptions:get|fixture(200)} diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index 635859bc7b..10951b0802 100644 --- a/zerver/lib/api_test_helpers.py +++ b/zerver/lib/api_test_helpers.py @@ -327,9 +327,8 @@ def list_subscriptions(client): result = client.list_subscriptions() # {code_example|end} - fixture = FIXTURES['get-subscribed-streams'] - test_against_fixture(result, fixture, check_if_equal=['msg', 'result'], - check_if_exists=['subscriptions']) + validate_against_openapi_schema(result, '/users/me/subscriptions', + 'get', '200') streams = [s for s in result['subscriptions'] if s['name'] == 'new stream'] assert streams[0]['description'] == 'New stream for testing' @@ -969,13 +968,13 @@ TEST_FUNCTIONS = { '/get_stream_id:get': get_stream_id, '/streams/{stream_id}:delete': delete_stream, '/streams/{stream_id}:patch': update_stream, - 'get-subscribed-streams': list_subscriptions, '/streams:get': get_streams, '/users:post': create_user, 'get-profile': get_profile, 'add-subscriptions': add_subscriptions, '/users/{email}/presence:get': get_user_presence, '/users/me/presence:post': update_presence, + '/users/me/subscriptions:get': list_subscriptions, '/users/me/subscriptions:delete': remove_subscriptions, '/users/me/subscriptions/muted_topics:patch': toggle_mute_topic, '/users/me/subscriptions/properties:post': update_subscription_settings, diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 8c40bb0b2b..a8cdee5af8 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -1115,6 +1115,69 @@ paths: "result": "error" } /users/me/subscriptions: + get: + description: Get information on every stream the user is subscribed to. + security: + - basicAuth: [] + responses: + '200': + description: Success. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/JsonSuccess' + - properties: + subscriptions: + type: array + items: + type: object + - example: + { + "msg": "", + "result": "success", + "subscriptions": [ + { + "audible_notifications": true, + "color": "#e79ab5", + "description": "A Scandinavian country", + "desktop_notifications": true, + "email_address": "Denmark+187b4125ed36d6af8b5d03ef4f65c0cf@zulipdev.com:9981", + "in_home_view": true, + "invite_only": false, + "name": "Denmark", + "pin_to_top": false, + "push_notifications": false, + "stream_id": 1, + "subscribers": [ + "ZOE@zulip.com", + "hamlet@zulip.com", + "iago@zulip.com", + "othello@zulip.com", + "prospero@zulip.com" + ] + }, + { + "audible_notifications": true, + "color": "#e79ab5", + "description": "Located in the United Kingdom", + "desktop_notifications": true, + "email_address": "Scotland+f5786390183e60a1ccb18374f9d05649@zulipdev.com:9981", + "in_home_view": true, + "invite_only": false, + "name": "Scotland", + "pin_to_top": false, + "push_notifications": false, + "stream_id": 3, + "subscribers": [ + "ZOE@zulip.com", + "iago@zulip.com", + "othello@zulip.com", + "prospero@zulip.com" + ] + } + ] + } post: description: Subscribe one or more users to one or more streams. parameters: @@ -1171,6 +1234,31 @@ paths: type: boolean default: true example: false + - name: history_public_to_subscribers + in: query + description: A boolean indicating if the history should be available to + newly subscribed members. + schema: + type: boolean + default: None + example: false + - name: is_announcement_only + in: query + description: A boolean indicating if the stream is an announcements only stream. + Only organization admins can post to announcements only streams. + schema: + type: boolean + default: false + example: false + - name: announce + in: query + description: If `announce` is `True` and one of the streams specified + in `subscriptions` has to be created (i.e. doesn't exist to begin + with), an announcement will be made notifying that a new stream was + created. + schema: + type: boolean + example: true security: - basicAuth: [] responses: @@ -1239,6 +1327,43 @@ paths: "private_stream" ] } + patch: + description: Update which streams you are are subscribed to. + parameters: + - name: delete + in: query + description: A list of stream names to unsubscribe from. + schema: + type: array + items: + type: string + example: ['Verona', 'Denmark'] + required: false + - name: add + in: query + description: A list of objects describing which streams to subscribe to, + optionally including per-user subscription parameters (e.g. color) + and if the stream is to be created, its description. + schema: + type: array + items: + type: object + items: + name: string + color: string + description: string + example: + [ + { + "name": "Verona" + }, + { + "name": "Denmark", + "color": "#e79ab5", + "description": "A Scandinavian country", + } + ] + required: false delete: description: Unsubscribe yourself or other users from one or more streams. diff --git a/zerver/tests/test_openapi.py b/zerver/tests/test_openapi.py index 9fb31a10c6..4c8ed18050 100644 --- a/zerver/tests/test_openapi.py +++ b/zerver/tests/test_openapi.py @@ -161,10 +161,6 @@ class OpenAPIArgumentsTest(ZulipTestCase): '/default_stream_groups/create', '/users/me/alert_words', '/users/me/status', - # This endpoint is legacy; documented using the old system - # defined in ./templates/zerver/api/fixtures.json, not - # zulip.yaml. Needs migrating. - '/users/me/subscriptions', '/messages/matches_narrow', '/settings', '/submessage', @@ -252,7 +248,7 @@ class OpenAPIArgumentsTest(ZulipTestCase): msg: Optional[str]=None) -> None: try: get_openapi_parameters(url_pattern, method) - if not msg: + if not msg: # nocoverage msg = """ We found some OpenAPI documentation for {method} {url_pattern}, so maybe we shouldn't mark it as intentionally undocumented in the urls. @@ -332,13 +328,6 @@ so maybe we shouldn't mark it as intentionally undocumented in the urls. regex_pattern = p.regex.pattern url_pattern = self.convert_regex_to_url_pattern(regex_pattern) - if url_pattern == "/users/me/subscriptions": - # Hack to workaround legacy pre-openapi docs. - # TODO: Migrate get-subscriptions out of - # ./templates/zerver/api/fixtures.json and into - # zerver/openapi/zulip.yaml. - continue - if "intentionally_undocumented" in tags: self.ensure_no_documentation_if_intentionally_undocumented(url_pattern, method) continue