mirror of https://github.com/zulip/zulip.git
api docs: Minor formatting improvements.
This commit is contained in:
Yago González
Tim Abbott
parent
90e3b8d808
commit
d45fac0327
|
|
@ -18,7 +18,7 @@ info:
|
|||
name: Apache 2.0
|
||||
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
||||
servers:
|
||||
- url: 'https://your.zulip.server/api/v1'
|
||||
- url: 'https://your.zulip.server/api/v1'
|
||||
|
||||
#######################
|
||||
# Endpoint definitions
|
||||
|
|
@ -61,7 +61,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -134,7 +134,7 @@ paths:
|
|||
"result": "success"
|
||||
}
|
||||
'400':
|
||||
description: Bad request
|
||||
description: Bad request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -180,7 +180,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -197,7 +197,7 @@ paths:
|
|||
"stream_id": 15
|
||||
}
|
||||
'400':
|
||||
description: Bad request
|
||||
description: Bad request.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -252,7 +252,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -313,19 +313,17 @@ paths:
|
|||
required: true
|
||||
- name: subject
|
||||
in: query
|
||||
description: |
|
||||
The topic of the message. Only required for stream messages.
|
||||
Maximum length of 60 characters.
|
||||
description: The topic of the message. Only required for stream
|
||||
messages. Maximum length of 60 characters.
|
||||
schema:
|
||||
type: string
|
||||
default:
|
||||
example: Castle
|
||||
- name: propagate_mode
|
||||
in: query
|
||||
description: |
|
||||
Which message(s) should be edited: just the one indicated in
|
||||
`message_id`, messages in the same topic that had been sent after
|
||||
this one, or all of them.
|
||||
description: "Which message(s) should be edited: just the one
|
||||
indicated in `message_id`, messages in the same topic that had been
|
||||
sent after this one, or all of them."
|
||||
schema:
|
||||
type: string
|
||||
enum:
|
||||
|
|
@ -336,8 +334,8 @@ paths:
|
|||
example: change_all
|
||||
- name: content
|
||||
in: query
|
||||
description: |
|
||||
The content of the message. Maximum message size of 10000 bytes.
|
||||
description: The content of the message. Maximum message size of 10000
|
||||
bytes.
|
||||
schema:
|
||||
type: string
|
||||
example: Hello
|
||||
|
|
@ -345,7 +343,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -386,7 +384,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -443,13 +441,13 @@ paths:
|
|||
can compute their own gravatars.
|
||||
schema:
|
||||
type: boolean
|
||||
default : false
|
||||
default: false
|
||||
example: true
|
||||
security:
|
||||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -565,7 +563,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -622,19 +620,17 @@ paths:
|
|||
parameters:
|
||||
- name: subscriptions
|
||||
in: query
|
||||
description: |
|
||||
A list of dictionaries, where each dictionary contains key/value
|
||||
pairs specifying a particular stream to subscribe to.
|
||||
description: "A list of dictionaries, where each dictionary contains
|
||||
key/value pairs specifying a particular stream to subscribe to.
|
||||
**Note**: This argument is called `streams` and not `subscriptions`
|
||||
in our Python API.
|
||||
in our Python API."
|
||||
schema:
|
||||
type: string
|
||||
type: array
|
||||
example: [{"name": "Verona"}]
|
||||
required: true
|
||||
- name: invite_only
|
||||
in: query
|
||||
description: |
|
||||
A boolean specifying whether the streams specified in
|
||||
description: A boolean specifying whether the streams specified in
|
||||
`subscriptions` are invite-only or not.
|
||||
schema:
|
||||
type: boolean
|
||||
|
|
@ -642,9 +638,8 @@ paths:
|
|||
example: true
|
||||
- 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
|
||||
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:
|
||||
|
|
@ -652,23 +647,21 @@ paths:
|
|||
example: true
|
||||
- name: principals
|
||||
in: query
|
||||
description: |
|
||||
A list of email addresses of the users that will be subscribed to
|
||||
the streams specified in the `subscriptions` argument. If not
|
||||
provided, then the requesting user/bot is subscribed.
|
||||
description: A list of email addresses of the users that will be
|
||||
subscribed to the streams specified in the `subscriptions` argument.
|
||||
If not provided, then the requesting user/bot is subscribed.
|
||||
schema:
|
||||
type: string
|
||||
type: array
|
||||
default: []
|
||||
example: ['ZOE@zulip.com']
|
||||
- name: authorization_errors_fatal
|
||||
in: query
|
||||
description: |
|
||||
A boolean specifying whether authorization errors (such as when the
|
||||
requesting user is not authorized to access a private stream) should
|
||||
be considered fatal or not. When `True`, an authorization error is
|
||||
reported as such. When set to `False`, the returned JSON payload
|
||||
indicates that there was an authorization error, but the response is
|
||||
still considered a successful one.
|
||||
description: A boolean specifying whether authorization errors (such
|
||||
as when the requesting user is not authorized to access a private
|
||||
stream) should be considered fatal or not. When `True`, an
|
||||
authorization error is reported as such. When set to `False`, the
|
||||
returned JSON payload indicates that there was an authorization
|
||||
error, but the response is still considered a successful one.
|
||||
schema:
|
||||
type: boolean
|
||||
default: true
|
||||
|
|
@ -677,7 +670,7 @@ paths:
|
|||
- basicAuth: []
|
||||
responses:
|
||||
'200_without_principals':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -695,7 +688,7 @@ paths:
|
|||
}
|
||||
}
|
||||
'200_already_subscribed':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -713,7 +706,7 @@ paths:
|
|||
"subscribed": {}
|
||||
}
|
||||
'400_unauthorized_errors_fatal_true':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -725,7 +718,7 @@ paths:
|
|||
"result": "error"
|
||||
}
|
||||
'400_unauthorized_errors_fatal_false':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -833,7 +826,7 @@ paths:
|
|||
that the user entered)
|
||||
schema:
|
||||
type: boolean
|
||||
default : false
|
||||
default: false
|
||||
example: true
|
||||
- name: client_gravatar
|
||||
in: query
|
||||
|
|
@ -841,7 +834,7 @@ paths:
|
|||
can compute their own gravatars.
|
||||
schema:
|
||||
type: boolean
|
||||
default : false
|
||||
default: false
|
||||
example: true
|
||||
- name: event_types
|
||||
in: query
|
||||
|
|
@ -873,7 +866,7 @@ paths:
|
|||
include the subscribers for each stream.
|
||||
schema:
|
||||
type: boolean
|
||||
default : false
|
||||
default: false
|
||||
example: true
|
||||
- name: fetch_event_types
|
||||
in: query
|
||||
|
|
@ -893,13 +886,13 @@ paths:
|
|||
`narrow=['is', 'private']` for private messages.
|
||||
schema:
|
||||
type: string
|
||||
default : narrow=[]
|
||||
default: narrow=[]
|
||||
example: narrow=['stream', 'Denmark']
|
||||
security:
|
||||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -943,14 +936,14 @@ paths:
|
|||
description: Include all public streams.
|
||||
schema:
|
||||
type: boolean
|
||||
default : true
|
||||
default: true
|
||||
example: false
|
||||
- name: include_subscribed
|
||||
in: query
|
||||
description: Include all streams that the user is subscribed to.
|
||||
schema:
|
||||
type: boolean
|
||||
default : true
|
||||
default: true
|
||||
example: false
|
||||
- name: include_all_active
|
||||
in: query
|
||||
|
|
@ -958,20 +951,20 @@ paths:
|
|||
administrative privileges to use this parameter.
|
||||
schema:
|
||||
type: boolean
|
||||
default : false
|
||||
default: false
|
||||
example: true
|
||||
- name: include_default
|
||||
in: query
|
||||
description: Include all default streams for the user's realm.
|
||||
schema:
|
||||
type: boolean
|
||||
default : false
|
||||
default: false
|
||||
example: true
|
||||
security:
|
||||
- basicAuth: []
|
||||
responses:
|
||||
'200':
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
@ -1050,10 +1043,9 @@ components:
|
|||
BasicAuth:
|
||||
type: http
|
||||
scheme: basic
|
||||
description: |
|
||||
Basic authentication, with the user's email as the username, and the
|
||||
API key as the password. The API key can be fetched using the
|
||||
`/fetch_api_key` or `/dev_fetch_api_key` endpoints.
|
||||
description: Basic authentication, with the user's email as the
|
||||
username, and the API key as the password. The API key can be fetched
|
||||
using the `/fetch_api_key` or `/dev_fetch_api_key` endpoints.
|
||||
|
||||
schemas:
|
||||
JsonResponse:
|
||||
|
|
@ -1117,30 +1109,27 @@ components:
|
|||
- properties:
|
||||
subscribed:
|
||||
type: object
|
||||
description: |
|
||||
A dictionary where the key is the email address of the user/bot
|
||||
and the value is a list of the names of the streams that were
|
||||
subscribed to as a result of the query.
|
||||
description: A dictionary where the key is the email address of
|
||||
the user/bot and the value is a list of the names of the streams
|
||||
that were subscribed to as a result of the query.
|
||||
already_subscribed:
|
||||
type: object
|
||||
description: |
|
||||
A dictionary where the key is the email address of the user/bot
|
||||
and the value is a list of the names of the streams that the
|
||||
user/bot is already subscribed to.
|
||||
description: A dictionary where the key is the email address of
|
||||
the user/bot and the value is a list of the names of the streams
|
||||
that the user/bot is already subscribed to.
|
||||
unauthorized:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
description: |
|
||||
A list of names of streams that the requesting user/bot was not
|
||||
authorized to subscribe to.
|
||||
description: A list of names of streams that the requesting
|
||||
user/bot was not authorized to subscribe to.
|
||||
|
||||
###################
|
||||
# Shared responses
|
||||
###################
|
||||
responses:
|
||||
SimpleSuccess:
|
||||
description: Success
|
||||
description: Success.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
|
|
|
|||
Loading…
Reference in New Issue