./ct_report/coverage/mongoose_client_api_rooms_messages_doc.COVER.html

1 %%% ==================================================================
2 %%% @doc
3 %%% This module provided documentation of MongooseIM client REST API Rooms: /api/rooms/[:id]/messages
4 %%% @end
5 %%% ==================================================================
6
7 -module(mongoose_client_api_rooms_messages_doc).
8
9 %%% ==================================================================
10 %%% Macros: HTTP Response Codes
11 %%% ==================================================================
12
13 -define(HTTP_200_OK, 200).
14 -define(HTTP_400_BAD_REQUEST, 400).
15 -define(HTTP_401_UNAUTHORIZED, 401).
16 -define(HTTP_403_FORBIDDEN, 403).
17 -define(HTTP_404_NOT_FOUND, 404).
18 -define(HTTP_500_INTERNAL_SERVER_ERROR, 500).
19
20 %%% ==================================================================
21 %%% Trails Callbacks
22 %%% ==================================================================
23
24 -behaviour(trails_handler).
25
26 -export([trails/0]).
27
28 trails() ->
29 %% Definitions
30 46 DefSendMesgRoomReq = <<"req-body-client-api-room-send-message">>,
31 46 DefMarkerRoomReq = <<"req-body-client-api-room-chat-marker">>,
32 46 DefSendMesgRoomResp = <<"resp-body-client-api-room-send-message">>,
33 46 DefGetMesgsRoomResp = <<"resp-body-client-api-room-get-messages">>,
34
35 %% Properties
36 46 PropRoomMsgReq = #{
37 <<"body">> => #{
38 type => <<"string">>,
39 description => <<"Required if chat marker property is not set.">>,
40 default => <<"Hello World!">>
41 },
42 <<"markable">> => #{
43 type => <<"boolean">>,
44 description => <<"May only be used when body is present as well">>,
45 default => true
46 },
47 <<"chat_marker">> => #{
48 type => <<"object">>,
49 description => <<"May be used independently of body and markable properties">>,
50 schema => cowboy_swagger:schema(DefMarkerRoomReq)
51 }
52 },
53
54 46 PropRoomMarkerReq = #{
55 <<"type">> => #{
56 type => <<"string">>,
57 description => <<"['received', 'displayed', 'acknowledged']">>,
58 default => <<"received">>
59 },
60 <<"id">> => #{
61 type => <<"string">>,
62 description => <<"ID">>,
63 default => <<"11-111-111">>
64 }
65 },
66
67 46 PropRoomGetMsgsResp = #{
68 <<"type">> => #{
69 type => <<"string">>,
70 description => <<"The type of a message, possible values are: 'message' for regular message 'affiliation' for affiliation changes. = ['message', 'affiliation']">>,
71 default => <<"message">>
72 },
73 <<"from">> => #{
74 type => <<"string">>,
75 description => <<"The JID of message sender. In case of a regular message sent by room's participant the JID will be a full JID with the sender's bare JID as a resource part of room's JID">>,
76 default => <<"alice@wonderland.com">>
77 },
78 <<"id">> => #{
79 type => <<"string">>,
80 description => <<"The ID of a message.">>,
81 default => <<"56c331f6-23f0-48a5-8007-23a5353ecac4">>
82 },
83 <<"timestamp">> => #{
84 type => <<"integer">>,
85 description => <<"Unix timestamp in miliseconds">>,
86 default => 1575632262307
87 },
88 <<"body">> => #{
89 type => <<"string">>,
90 description => <<"The message body. Present only if the type is 'message'">>,
91 default => <<"Hello World!">>
92 },
93 <<"user">> => #{
94 type => <<"string">>,
95 description => <<"JID of a user, whom affiliation changed. Present only if the type is 'affiliation'">>,
96 default => <<"alice@wonderland.com">>
97 },
98 <<"affiliation">> => #{
99 type => <<"string">>,
100 description => <<"The new affiliation of a user in the room. Present only if the type is 'affiliation'">>,
101 default => <<"owner">>
102 },
103 <<"markable">> => #{
104 type => <<"boolean">>,
105 description => <<"The markable if body is present as well">>,
106 default => true
107 },
108 <<"chat_marker">> => #{
109 type => <<"object">>,
110 description => <<"The chat_marker independently of body and markable properties">>,
111 schema => cowboy_swagger:schema(DefMarkerRoomReq)
112 }
113 },
114
115 46 PropRoomMarkerReq = #{
116 <<"type">> => #{
117 type => <<"string">>,
118 description => <<"['received', 'displayed', 'acknowledged']">>,
119 default => <<"received">>
120 },
121 <<"id">> => #{
122 type => <<"string">>,
123 description => <<"ID">>,
124 default => <<"11-111-111">>
125 }
126 },
127
128 46 PropRoomSendMsgsResp = #{
129 <<"id">> => #{
130 type => <<"string">>,
131 description => <<"ID">>,
132 default => <<"50009d9e-fa7f-4cf1-a291-b70b7decdc58">>
133 }
134 },
135
136 %% Definitions and properties
137 46 DefinitionsAndProperties = [
138 {DefSendMesgRoomReq, PropRoomMsgReq},
139 {DefMarkerRoomReq, PropRoomMarkerReq},
140 {DefSendMesgRoomResp, PropRoomSendMsgsResp},
141 {DefGetMesgsRoomResp, PropRoomGetMsgsResp}
142 ],
143
144 %% Add definitions
145 46 lists:foreach(
146 fun({Definition, DefinitionProperties}) ->
147 184 cowboy_swagger:add_definition(Definition, DefinitionProperties)
148 end, DefinitionsAndProperties),
149
150 %% Request Body
151 46 RequestBodyMsgRoom = #{
152 in => body,
153 name => <<"message">>,
154 type => <<"object">>,
155 description => <<"Message">>,
156 required => true,
157 schema => cowboy_swagger:schema(DefSendMesgRoomReq)
158 },
159
160 %% Pushs
161 46 RequestPushRoomId = #{
162 in => path,
163 name => <<"id">>,
164 type => <<"string">>,
165 description => <<"The ID of a room">>,
166 default => <<"1575-564351-207767">>,
167 required => true
168 },
169
170 %% Querys
171 46 RequestQueryRoomLimit = #{
172 in => query,
173 name => <<"limit">>,
174 type => <<"integer">>,
175 description => <<"Specifies the maximum number of messages to be returned. Default value is 50">>,
176 default => 10
177 },
178
179 46 RequestQueryRoomBefore = #{
180 in => query,
181 name => <<"before">>,
182 type => <<"integer">>,
183 description => <<"The timestamp in milliseconds. If set, only messages before this date will be returned">>,
184 default => 1575632262307
185 },
186
187 %% Meta data
188 46 MetadataClientApiRoomUsers = #{
189 post => #{
190 tags => ["Rooms"],
191 description => <<"Send a message to a room">>,
192 consumes => ["application/json"],
193 produces => ["application/json"],
194 parameters => [RequestPushRoomId, RequestBodyMsgRoom],
195 responses => #{
196 ?HTTP_200_OK => #{description => <<"OK">>, schema => cowboy_swagger:schema(DefSendMesgRoomResp)},
197 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
198 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
199 ?HTTP_403_FORBIDDEN => #{description => <<"When the authenticated user is not allowed to add users to the room">>},
200 ?HTTP_404_NOT_FOUND => #{description => <<"When there is no room with the given ID">>},
201 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
202 }
203 },
204 get => #{
205 tags => ["Rooms"],
206 description => <<"Gets room's messages from the archive">>,
207 parameters => [RequestPushRoomId, RequestQueryRoomLimit, RequestQueryRoomBefore],
208 responses => #{
209 ?HTTP_200_OK => #{description => <<"OK">>, schema => cowboy_swagger:schema(DefGetMesgsRoomResp)},
210 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
211 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
212 ?HTTP_403_FORBIDDEN => #{description => <<"When the authenticated user is not allowed to add users to the room">>},
213 ?HTTP_404_NOT_FOUND => #{description => <<"When there is no room with the given ID">>},
214 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
215 }
216 }
217 },
218
219 %% Paths
220 46 PathClientApiRoomsConfig = "/api/rooms/[:id]/messages",
221
222 %% Options
223 46 StoreOptions = [
224 {PathClientApiRoomsConfig, #{path => PathClientApiRoomsConfig}, MetadataClientApiRoomUsers, mongoose_client_api_rooms_messages}
225 ],
226
227 %% Trail all data
228 46 [trails:trail(Path, Module, Options, Metadata) || {Path, Options, Metadata, Module} <- StoreOptions].
Line Hits Source