Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api docs: Migrate POST /messages to OpenAPI.

This commit is contained in:
Yago González 2018-06-18 18:15:08 +02:00 committed by Tim Abbott
parent cb24756edc
commit 7ddc6e8d10
5 changed files with 111 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
templates/zerver/api/arguments.json
View File

@ -1,30 +1,4 @@
{
"send-message.md": [
{
"argument": "type",
"description": "The type of message to be sent. `stream` for a stream message and `private` for a private message.",
"required": true,
"example": "stream"
},
{
"argument": "to",
"description": "A string identifying the stream.",
"required": true,
"example": "Denmark"
},
{
"argument": "subject",
"description": "The topic of the message. Only required if `type` is `stream`. Defaults to `None`. Maximum length of 60 characters.",
"required": false,
"example": "Castle"
},
{
"argument": "content",
"description": "The content of the message. Maximum message size of 10000 bytes.",
"required": true,
"example": "Hello"
}
],
"get-all-streams.md": [
{
"argument": "include_public",

10
templates/zerver/api/fixtures.json
View File

@ -249,11 +249,6 @@
"msg": "Invalid API key",
"result": "error"
},
"invalid-pm-recipient-error": {
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error"
},
"invalid-stream-error": {
"code": "BAD_REQUEST",
"msg": "Invalid stream name 'nonexistent'",
@ -303,11 +298,6 @@
"rendered": "<p><strong>foo</strong></p>",
"result": "success"
},
"send-message": {
"id": 134,
"msg": "",
"result": "success"
},
"successful-response-empty": {
"msg": "",
"result": "success"

10
templates/zerver/api/send-message.md
View File

@ -38,7 +38,7 @@ curl {{ api_url }}/v1/messages \
<div data-language="python" markdown="1">
{generate_code_example(python)|send-message|example}
{generate_code_example(python)|/messages:post|example}
</div>
@ -117,7 +117,7 @@ zulip(config).then((client) => {
## Arguments
{generate_api_arguments_table|arguments.json|send-message.md}
{generate_api_arguments_table|zulip.yaml|/messages:post}
## Response
@ -128,14 +128,14 @@ zulip(config).then((client) => {
#### Example response
A typical successful JSON response may look like:
{generate_code_example|send-message|fixture}
{generate_code_example|/messages:post|fixture(200)}
A typical failed JSON response for when a stream message is sent to a stream
that does not exist:
{generate_code_example|nonexistent-stream-error|fixture}
{generate_code_example|/messages:post|fixture(400_non_existing_stream)}
A typical failed JSON response for when a private message is sent to a user
that does not exist:
{generate_code_example|invalid-pm-recipient-error|fixture}
{generate_code_example|/messages:post|fixture(400_non_existing_user)}

17
zerver/lib/api_test_helpers.py
View File

@ -307,9 +307,7 @@ def send_message(client):
result = client.send_message(request)
# {code_example|end}
fixture = FIXTURES['send-message']
test_against_fixture(result, fixture, check_if_equal=['result'],
check_if_exists=['id'])
validate_against_openapi_schema(result, '/messages', 'post', '200')
# test that the message was actually sent
message_id = result['id']
@ -331,8 +329,7 @@ def send_message(client):
result = client.send_message(request)
# {code_example|end}
test_against_fixture(result, fixture, check_if_equal=['result'],
check_if_exists=['id'])
validate_against_openapi_schema(result, '/messages', 'post', '200')
# test that the message was actually sent
message_id = result['id']
@ -356,8 +353,8 @@ def test_nonexistent_stream_error(client):
}
result = client.send_message(request)
fixture = FIXTURES['nonexistent-stream-error']
test_against_fixture(result, fixture)
validate_against_openapi_schema(result, '/messages', 'post',
'400_non_existing_stream')
def test_private_message_invalid_recipient(client):
# type: (Client) -> None
@ -368,8 +365,8 @@ def test_private_message_invalid_recipient(client):
}
result = client.send_message(request)
fixture = FIXTURES['invalid-pm-recipient-error']
test_against_fixture(result, fixture)
validate_against_openapi_schema(result, '/messages', 'post',
'400_non_existing_user')
def update_message(client, message_id):
# type: (Client, int) -> None
@ -503,7 +500,7 @@ def test_invalid_stream_error(client):
TEST_FUNCTIONS = {
'render-message': render_message,
'send-message': send_message,
'/messages:post': send_message,
'/messages/{message_id}:patch': update_message,
'get-stream-id': get_stream_id,
'get-subscribed-streams': list_subscriptions,

99
zerver/openapi/zulip.yaml
View File

@ -24,6 +24,97 @@ servers:
# Endpoint definitions
#######################
paths:
/messages:
post:
description: Send a message.
parameters:
- name: type
in: query
description: The type of message to be sent. `private` for a private
message and `stream` for a stream message.
schema:
type: string
enum:
- private
- stream
example: private
required: true
- name: to
in: query
description: The destination stream, or a CSV/JSON-encoded list
containing the usernames (emails) of the recipients.
schema:
type: string
example: aaron@zulip.com, iago@zulip.com
required: true
- name: subject
in: query
description: The topic of the message. Only required if `type` is
`stream`, ignored otherwise. Maximum length of 60 characters.
schema:
type: string
default:
example: Castle
- name: content
in: query
description: The content of the message. Maximum message size of
10000 bytes.
schema:
type: string
example: Hello
required: true
security:
- basicAuth: []
responses:
'200':
description: Success
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/JsonSuccess'
- properties:
id:
type: integer
description: The ID assigned to the message sent.
- example:
{
"msg": "",
"id": 42,
"result": "success"
}
'400_non_existing_stream':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- properties:
stream:
type: string
description: The name of the stream that could not be
found.
- example:
{
"code": "STREAM_DOES_NOT_EXIST",
"msg": "Stream 'nonexistent_stream' does not exist",
"result": "error",
"stream": "nonexistent_stream"
}
'400_non_existing_user':
description: Bad request.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CodedError'
- example:
{
"code": "BAD_REQUEST",
"msg": "Invalid email 'eeshan@zulip.com'",
"result": "error"
}
/messages/{message_id}:
patch:
description: Edit a message that has already been sent.
@ -287,6 +378,7 @@ paths:
]
}
components:
#######################
# Security definitions
@ -335,6 +427,13 @@ components:
- error
msg:
type: string
CodedError:
allOf:
- $ref: '#/components/schemas/JsonError'
- properties:
code:
type: string
description: A string that identifies the error.
AddSubscriptionsResponse:
allOf:
- $ref: '#/components/schemas/JsonSuccess'