From 14c92770952c204ef1db0ff3f1af9f59a93343a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yago=20Gonz=C3=A1lez?= Date: Thu, 21 Jun 2018 01:47:22 +0200 Subject: [PATCH] api docs: Migrate POST /users to OpenAPI. --- templates/zerver/api/arguments.json | 26 --------------- templates/zerver/api/create-user.md | 8 ++--- templates/zerver/api/fixtures.json | 4 --- zerver/lib/api_test_helpers.py | 8 ++--- zerver/openapi/zulip.yaml | 52 +++++++++++++++++++++++++++++ 5 files changed, 59 insertions(+), 39 deletions(-) diff --git a/templates/zerver/api/arguments.json b/templates/zerver/api/arguments.json index 4eb404f785..286bac76b1 100644 --- a/templates/zerver/api/arguments.json +++ b/templates/zerver/api/arguments.json @@ -39,32 +39,6 @@ "example": "change_all" } ], - "create-user.md": [ - { - "argument": "email", - "description": "The email address of the new user.", - "required": true, - "example": "newbie@zulip.com" - }, - { - "argument": "password", - "description": "The password of the new user.", - "required": true, - "example": "abdec@7982" - }, - { - "argument": "full_name", - "description": "The full name of the new user.", - "required": true, - "example": "John Smith" - }, - { - "argument": "short_name", - "description": "The short name of the new user.", - "required": true, - "example": "jsmith" - } - ], "remove-subscriptions.md": [ { "argument": "subscriptions", diff --git a/templates/zerver/api/create-user.md b/templates/zerver/api/create-user.md index 07ea322960..11244ce2ff 100644 --- a/templates/zerver/api/create-user.md +++ b/templates/zerver/api/create-user.md @@ -31,7 +31,7 @@ curl {{ api_url }}/v1/users \
-{generate_code_example(python)|create-user|example(admin_config=True)} +{generate_code_example(python)|/users:post|example(admin_config=True)}
@@ -64,7 +64,7 @@ zulip(config).then((client) => { ## Arguments -{generate_api_arguments_table|arguments.json|create-user.md} +{generate_api_arguments_table|zulip.yaml|/users:post} ## Response @@ -72,9 +72,9 @@ zulip(config).then((client) => { A typical successful JSON response may look like: -{generate_code_example|successful-response-empty|fixture} +{generate_code_example|/users:post|fixture(200)} A typical JSON response for when another user with the same email address already exists in the realm: -{generate_code_example|email_already_used_error|fixture} +{generate_code_example|/users:post|fixture(400)} diff --git a/templates/zerver/api/fixtures.json b/templates/zerver/api/fixtures.json index 334414bb33..f089755f39 100644 --- a/templates/zerver/api/fixtures.json +++ b/templates/zerver/api/fixtures.json @@ -5,10 +5,6 @@ "queue_id": "1518820930:1", "result": "error" }, - "email_already_used_error": { - "msg": "Email 'newbie@zulip.com' already in use", - "result": "error" - }, "get-profile": { "client_id": "74c768b081076fdb3c4326256c17467e", "email": "iago@zulip.com", diff --git a/zerver/lib/api_test_helpers.py b/zerver/lib/api_test_helpers.py index cf8b5ebd0b..95c5d10a84 100644 --- a/zerver/lib/api_test_helpers.py +++ b/zerver/lib/api_test_helpers.py @@ -113,14 +113,12 @@ def create_user(client): result = client.create_user(request) # {code_example|end} - fixture = FIXTURES['successful-response-empty'] - test_against_fixture(result, fixture) + validate_against_openapi_schema(result, '/users', 'post', '200') # Test "Email already used error" result = client.create_user(request) - fixture = FIXTURES['email_already_used_error'] - test_against_fixture(result, fixture) + validate_against_openapi_schema(result, '/users', 'post', '400') def get_members(client): # type: (Client) -> None @@ -474,7 +472,7 @@ TEST_FUNCTIONS = { '/get_stream_id:get': get_stream_id, 'get-subscribed-streams': list_subscriptions, '/streams:get': get_streams, - 'create-user': create_user, + '/users:post': create_user, 'get-profile': get_profile, 'add-subscriptions': add_subscriptions, 'remove-subscriptions': remove_subscriptions, diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index 6d3c4befe4..ed06472c8a 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -467,6 +467,58 @@ paths: "msg": "", "result": "success" } + post: + description: Create a new user in a realm. + parameters: + - name: email + in: query + description: The email address of the new user. + schema: + type: string + example: newbie@zulip.com + required: true + - name: password + in: query + description: The password of the new user. + schema: + type: string + example: abdec@7982 + required: true + - name: full_name + in: query + description: The full name of the new user. + schema: + type: string + example: John Smith + required: true + - name: short_name + in: query + description: The short name of the new user. + schema: + type: string + example: jsmith + required: true + security: + - basicAuth: [] + responses: + '200': + description: Success. + content: + application/json: + schema: + $ref: '#/components/schemas/JsonSuccess' + '400': + description: Bad request. + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/JsonError' + - example: + { + "msg": "Email 'newbie@zulip.com' already in use", + "result": "error" + } /users/me/{stream_id}/topics: get: description: Get all the topics in a specific stream.