./ct_report/coverage/mongoose_client_api_contacts_doc.COVER.html

1 %%% ==================================================================
2 %%% @doc
3 %%% This module provided documentation of MongooseIM client REST API Contacts: /api/contacts/[:jid]
4 %%% @end
5 %%% ==================================================================
6
7 -module(mongoose_client_api_contacts_doc).
8
9 %%% ==================================================================
10 %%% Macros: HTTP Response Codes
11 %%% ==================================================================
12
13 -define(HTTP_200_OK, 200).
14 -define(HTTP_204_NO_CONTENT, 204).
15 -define(HTTP_400_BAD_REQUEST, 400).
16 -define(HTTP_401_UNAUTHORIZED, 401).
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 97 DefPostContsReq = <<"req-body-client-api-post-contacts">>,
31 97 DefSucsGetAllConts = <<"resp-success-body-client-api-contacts-get-all">>,
32 97 DefDelConts = <<"req-body-client-api-contacts-del-contacts">>,
33 97 DefSucsDelConts = <<"resp-success-client-api-contacts-del-contacts">>,
34 97 DefContactsAction = <<"req-action-client-api-contacts-put-contacts">>,
35
36 %% Properties
37 97 PropPostContsReq = #{
38 <<"jid">> => #{
39 type => <<"string">>,
40 description => <<"This is user's JID (Jabber ID) which consist of username and server. Example: alice@wonderland.com">>,
41 default => <<"alice@wonderland.lit">>
42 }
43 },
44
45 97 PropSucsGetAllContsResp = #{
46 <<"jid">> => #{
47 type => <<"string">>,
48 description => <<"JID of roster">>,
49 default => <<"alice@wonderland.lit">>
50 },
51 <<"subscription">> => #{
52 type => <<"string">>,
53 description => <<"Subscription state of me vs contact. there are four possible state: 'none', 'both', 'to' - I receive updates about the contact's presence, 'from' - the contact receives updates about my presence">>,
54 default => <<"none">>
55 },
56 <<"ask">> => #{
57 type => <<"string">>,
58 description => <<"Tells whether one of us has asked the other for subscription to presence info and is waiting for approval. Possible states: 'none', 'both', 'out' - I asked the contact and am waiting for his approval, 'in' - my contact asked me, it is up to me to decide">>,
59 default => <<"none">>
60 }
61 },
62
63 97 PropContactToDelete = #{
64 <<"to_delete">> => #{
65 type => <<"array">>,
66 description => <<"Returns a list of not deleted users">>,
67 items => #{
68 type => <<"string">>,
69 default => <<"alice@wonderland.lit">>
70 }
71 }
72 },
73
74 97 PropSucsContactsToDelete = #{
75 <<"not_deleted">> => #{
76 type => <<"array">>,
77 description => <<"Returns a list of not deleted users">>,
78 items => #{
79 type => <<"string">>,
80 default => <<"alice@wonderland.lit">>
81 }
82 }
83 },
84
85 97 PropPutContactUserAction = #{
86 <<"action">> => #{
87 type => <<"string">>,
88 description => <<"Can be 'invite' or 'accept'">>,
89 default => <<"invite">>
90 }
91 },
92
93 %% Definitions and properties
94 97 DefinitionsAndProperties = [
95 {DefPostContsReq, PropPostContsReq},
96 {DefSucsGetAllConts, PropSucsGetAllContsResp},
97 {DefDelConts, PropContactToDelete},
98 {DefSucsDelConts, PropSucsContactsToDelete},
99 {DefContactsAction, PropPutContactUserAction}
100 ],
101
102 %% Add definitions
103 97 lists:foreach(
104 fun({Definition, DefinitionProperties}) ->
105 485 cowboy_swagger:add_definition(Definition, DefinitionProperties)
106 end, DefinitionsAndProperties),
107
108 %% Request Body
109 97 RequestPostBodyContact = #{
110 name => <<"Request Body">>,
111 in => body,
112 required => true,
113 description => <<"Contact body">>,
114 schema => cowboy_swagger:schema(DefPostContsReq)
115 },
116
117 97 RequestBodyContactsDelete = #{
118 name => <<"contacts">>,
119 in => body,
120 required => true,
121 type => <<"object">>,
122 schema => cowboy_swagger:schema(DefDelConts)
123 },
124
125 97 RequestBodyContactsUserAction = #{
126 name => <<"action">>,
127 in => body,
128 required => true,
129 type => <<"object">>,
130 description => <<"Can be 'invite' or 'accept'">>,
131 schema => cowboy_swagger:schema(DefContactsAction)
132 },
133
134 %% Pushs
135 97 RequestPushContactWith = #{
136 in => path,
137 name => <<"jid">>,
138 type => <<"string">>,
139 description => <<"User JID. Example: alice@wonderland.com.">>,
140 default => <<"alice@wonderland.lit">>,
141 required => true
142 },
143
144 %% Success responses
145 97 SucsGetAllConts = #{
146 type => <<"array">>,
147 items => #{
148 type => <<"object">>,
149 schema => cowboy_swagger:schema(DefSucsGetAllConts)
150 }
151 },
152
153 %% Meta data
154 97 MetadataClientApiContacts = #{
155 post => #{
156 tags => ["Contacts"],
157 description => <<"Adds a user to a contact list.">>,
158 consumes => ["application/json"],
159 produces => ["application/json"],
160 parameters => [RequestPostBodyContact],
161 responses => #{
162 ?HTTP_204_NO_CONTENT => #{description => <<"No Content">>},
163 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
164 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
165 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
166 }
167 },
168 get => #{
169 tags => ["Contacts"],
170 description => <<"Returns all contacts from the user's roster">>,
171 produces => ["application/json"],
172 responses => #{
173 ?HTTP_200_OK => #{description => <<"OK">>, schema => SucsGetAllConts},
174 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
175 ?HTTP_400_BAD_REQUEST => #{description => <<"Bad Request">>},
176 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
177 }
178 },
179 delete => #{
180 tags => ["Contacts"],
181 description => <<"Removes a list of users">>,
182 consumes => ["application/json"],
183 produces => ["application/json"],
184 parameters => [RequestBodyContactsDelete],
185 responses => #{
186 ?HTTP_200_OK => #{description => <<"OK">>, schema => cowboy_swagger:schema(DefSucsDelConts)},
187 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
188 ?HTTP_404_NOT_FOUND => #{description => <<"Not Found">>},
189 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
190 }
191 }
192 },
193
194 %% Meta data
195 97 MetadataClientApiWithJid = #{
196 delete => #{
197 tags => ["Contacts"],
198 description => <<"Removes contact">>,
199 parameters => [RequestPushContactWith],
200 responses => #{
201 ?HTTP_204_NO_CONTENT => #{description => <<"No Content">>},
202 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
203 ?HTTP_404_NOT_FOUND => #{description => <<"Not Found">>},
204 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
205 }
206 },
207 put => #{
208 tags => ["Contacts"],
209 description => <<"Manage subscription">>,
210 produces => ["application/json"],
211 parameters => [RequestBodyContactsUserAction, RequestPushContactWith],
212 responses => #{
213 ?HTTP_204_NO_CONTENT => #{description => <<"A subscription request was sent to the contact with value 'subscribe' or 'subscribed' (it may and may not change the 'subscription' and 'ask' states, depending what they were)">>},
214 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
215 ?HTTP_404_NOT_FOUND => #{description => <<"The contact is not in the user's roster">>},
216 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
217 }
218 }
219 },
220
221 %% Paths
222 97 PathClientApiContacts = "/api/contacts",
223 97 PathClientApiContactsWithJid = "/api/contacts/[:jid]",
224
225 %% Options
226 97 StoreOptions = [
227 {PathClientApiContacts, #{path => PathClientApiContacts}, MetadataClientApiContacts, mongoose_client_api_contacts},
228 {PathClientApiContactsWithJid, #{path => PathClientApiContactsWithJid}, MetadataClientApiWithJid, mongoose_client_api_contacts}
229 ],
230
231 %% Trail all data
232 97 [trails:trail(Path, Module, Options, Metadata) || {Path, Options, Metadata, Module} <- StoreOptions].
Line Hits Source