./ct_report/coverage/mongoose_client_api_messages_doc.COVER.html

1 %%% ==================================================================
2 %%% @doc
3 %%% This module provided documentation of MongooseIM client REST API Messages: /api/messages/[:with]
4 %%% This module can be used as base template for other custom REST API documentation
5 %%% @end
6 %%% ==================================================================
7
8 -module(mongoose_client_api_messages_doc).
9
10 %%% ==================================================================
11 %%% Macros: HTTP Response Codes
12 %%% ==================================================================
13
14 -define(HTTP_200_OK, 200).
15 -define(HTTP_400_BAD_REQUEST, 400).
16 -define(HTTP_401_UNAUTHORIZED, 401).
17 -define(HTTP_500_INTERNAL_SERVER_ERROR, 500).
18
19 %%% ==================================================================
20 %%% Trails Callbacks
21 %%% ==================================================================
22
23 -behaviour(trails_handler).
24
25 -export([trails/0]).
26
27 trails() ->
28 %% Definitions
29 46 DefSendMsgsReq = <<"req-body-client-api-send-messages">>,
30 46 DefSendMsgsResp = <<"resp-body-client-api-send-messages">>,
31 46 DefSucsSendMsgsResp = <<"resp-success-body-client-api-send-messages">>,
32
33 %% Properties
34 46 PropSendMsgsReq = #{
35 <<"to">> => #{
36 type => <<"string">>,
37 description => <<"This is user's JID (Jabber ID) which consist of username and server. Example: alice@wonderland.com">>,
38 default => <<"alice@wonderland.lit">>
39 },
40 <<"body">> => #{
41 type => <<"string">>,
42 description => <<"Message body">>,
43 default => <<"Hello Alice!">>
44 }
45 },
46
47 46 PropSendMsgsResp = #{
48 <<"id">> => #{
49 type => <<"string">>,
50 default => <<"76bcaa97-a114-4cb0-b783-ff929d8d8428">>
51 }
52 },
53
54 46 PropSucsSendMsgsResp = #{
55 <<"to">> => #{
56 type => <<"string">>,
57 description => <<"The message recipient's bare JID">>,
58 default => <<"alice@wonderland.lit">>
59 },
60 <<"from">> => #{
61 type => <<"string">>,
62 description => <<"The message sender's bare JID">>,
63 default => <<"rabbit@wonderland.lit">>
64 },
65 <<"timestamp">> => #{
66 type => <<"integer">>,
67 description => <<"Unix timestamp in milliseconds when the message was sent">>,
68 default => 1478258324908
69 },
70 <<"id">> => #{
71 type => <<"string">>,
72 description => <<"ID of message">>,
73 default => <<"76bcaa97-a114-4cb0-b783-ff929d8d8428">>
74 },
75 <<"body">> => #{
76 type => <<"string">>,
77 description => <<"Message content">>,
78 default => <<"Hello Alice!">>
79 },
80 <<"thread">> => #{
81 type => <<"string">>,
82 description => <<"ID of thread">>,
83 default => <<"e0ffe42b28561960c6b12b944a092794b9683a38">>
84 },
85 <<"parent">> => #{
86 type => <<"string">>,
87 description => <<"ID of thread parent">>,
88 default => <<"7edac73ab41e45c4aafa7b2d7b749080">>
89 }
90 },
91
92 %% Definitions and properties
93 46 DefinitionsAndProperties = [
94 {DefSendMsgsReq, PropSendMsgsReq},
95 {DefSendMsgsResp, PropSendMsgsResp},
96 {DefSucsSendMsgsResp, PropSucsSendMsgsResp}
97 ],
98
99 %% Add definitions
100 46 lists:foreach(
101 fun({Definition, DefinitionProperties}) ->
102 138 cowboy_swagger:add_definition(Definition, DefinitionProperties)
103 end, DefinitionsAndProperties),
104
105 %% Request Body
106 46 RequestBodyMessages = #{
107 name => <<"Request Body">>,
108 in => body,
109 required => true,
110 description => <<"The message to be sent">>,
111 schema => cowboy_swagger:schema(DefSendMsgsReq)
112 },
113
114 %% Querys
115 46 RequestQueryGetLimitMessages = #{
116 name => <<"limit">>,
117 description => <<"Specifies the maximum number of messages to be returned. Default value is 50.">>,
118 in => query,
119 type => <<"integer">>,
120 default => 10
121 },
122
123 46 RequestQueryGetBeforeMessages = #{
124 name => <<"before">>,
125 description => <<"The timestamp in milliseconds. If set, only messages before this date will be returned.">>,
126 in => query,
127 type => <<"integer">>,
128 default => 1478258324908
129 },
130
131 %% Pushs
132 46 RequestPushGetMessagesWith = #{
133 in => path,
134 name => <<"with">>,
135 type => <<"string">>,
136 description => <<"JID of the user with whom the messages were exchanged. Example: alice@wonderland.com.">>,
137 default => <<"alice@wonderland.com">>,
138 required => true
139 },
140
141 %% Success responses
142 46 SucsGetMesgs = #{
143 type => <<"array">>,
144 items => #{
145 type => <<"object">>,
146 schema => cowboy_swagger:schema(DefSucsSendMsgsResp)
147 }
148 },
149
150 %% Meta data
151 46 MetadataClientApiMessages = #{
152 get => #{
153 tags => ["One-to-one messages"],
154 description => <<"Gets all recent messages from all users from the archive.">>,
155 consumes => ["application/json"],
156 produces => ["application/json"],
157 parameters => [RequestQueryGetLimitMessages, RequestQueryGetBeforeMessages],
158 responses => #{
159 ?HTTP_200_OK => #{description => <<"OK">>, schema => SucsGetMesgs},
160 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
161 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
162 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
163 }
164 },
165 post => #{
166 tags => ["One-to-one messages"],
167 description => <<"Sends messages.">>,
168 consumes => ["application/json"],
169 produces => ["application/json"],
170 parameters => [RequestBodyMessages],
171 responses => #{
172 ?HTTP_200_OK => #{description => <<"OK">>, schema => cowboy_swagger:schema(DefSendMsgsResp)},
173 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
174 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
175 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
176 }
177 }
178 },
179
180 46 MetadataClientApiMessagesGetWith = #{
181 get => #{
182 tags => ["One-to-one messages"],
183 description => <<"Gets all recent messages from specified user from the archive.">>,
184 consumes => ["application/json"],
185 produces => ["application/json"],
186 parameters => [RequestPushGetMessagesWith, RequestQueryGetLimitMessages, RequestQueryGetBeforeMessages],
187 responses => #{
188 ?HTTP_200_OK => #{description => <<"OK">>, schema => SucsGetMesgs},
189 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
190 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
191 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
192 }
193 }
194 },
195
196 %% Paths
197 46 PathClientApiMessages = "/api/messages",
198 46 PathClientApiMessagesWith = "/api/messages/[:with]",
199
200 %% Options
201 46 StoreOptions = [
202 {PathClientApiMessages, #{path => PathClientApiMessages}, MetadataClientApiMessages, mongoose_client_api_messages},
203 {PathClientApiMessagesWith, #{path => PathClientApiMessagesWith}, MetadataClientApiMessagesGetWith, mongoose_client_api_messages}
204 ],
205
206 %% Trail all data
207 46 [trails:trail(Path, Module, Options, Metadata) || {Path, Options, Metadata, Module} <- StoreOptions].
Line Hits Source