./ct_report/coverage/mongoose_client_api_rooms_doc.COVER.html

1 %%% ==================================================================
2 %%% @doc
3 %%% This module provided documentation of MongooseIM client REST API Rooms: /api/rooms/[:id]
4 %%% @end
5 %%% ==================================================================
6
7 -module(mongoose_client_api_rooms_doc).
8
9 %%% ==================================================================
10 %%% Macros: HTTP Response Codes
11 %%% ==================================================================
12
13 -define(HTTP_200_OK, 200).
14 -define(HTTP_201_CREATED, 201).
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 46 DefCreateRoomReq = <<"req-body-client-api-create-room">>,
31 46 DefSucsGetRoomsResp = <<"resp-success-body-client-api-get-rooms">>,
32 46 DefSucsCreateRoomResp = <<"resp-success-body-client-api-create-room">>,
33 46 DefSucsGetRoomWithIdResp = <<"resp-success-body-client-api-get-room-with-id">>,
34 46 DefSucsGetRoomItemWithIdResp = <<"resp-success-body-client-api-get-room-item-with-id">>,
35
36 %% Properties
37 46 PropCreateRoomReq = #{
38 <<"subject">> => #{
39 type => <<"string">>,
40 description => <<"The subject of the room">>,
41 default => <<"Only important things">>
42 },
43 <<"name">> => #{
44 type => <<"string">>,
45 description => <<"The room's name">>,
46 default => <<"Important room">>
47 }
48 },
49
50 46 PropGetRoomsResp = #{
51 <<"id">> => #{
52 type => <<"string">>,
53 description => <<"Room's ID">>,
54 default => <<"1575-564351-207767">>
55 },
56 <<"subject">> => #{
57 type => <<"string">>,
58 description => <<"The subject of the room">>,
59 default => <<"Only important things">>
60 },
61 <<"name">> => #{
62 type => <<"string">>,
63 description => <<"The room's name">>,
64 default => <<"Important room">>
65 }
66 },
67
68 46 PropCreateRoomResp = #{
69 <<"id">> => #{
70 type => <<"id">>,
71 description => <<"Room's ID">>,
72 default => <<"1575-564351-207767">>
73 }
74 },
75
76 46 PropItemGetRoomWithIdResp = #{
77 <<"user">> => #{
78 type => <<"string">>,
79 description => <<"This is the user's JID (Jabber ID) which consist of username and server parts. Example: alice@wonderland.com">>,
80 default => <<"alice@wonderland.com">>
81 },
82 <<"role">> => #{
83 type => <<"string">>,
84 description => <<"The role of the user in a given room (can be 'owner' or 'member'). = ['owner', 'member']">>,
85 default => <<"owner">>
86 }
87 },
88
89 46 PropGetRoomWithIdResp = #{
90 <<"subject">> => #{
91 type => <<"string">>,
92 description => <<"The subject of the room">>,
93 default => <<"Only important things">>
94 },
95 <<"name">> => #{
96 type => <<"string">>,
97 description => <<"The room's name">>,
98 default => <<"Important room">>
99 },
100 <<"participants">> => #{
101 type => <<"array">>,
102 description => <<"Participants">>,
103 items => cowboy_swagger:schema(DefSucsGetRoomItemWithIdResp)
104 }
105 },
106
107 %% Definitions and properties
108 46 DefinitionsAndProperties = [
109 {DefCreateRoomReq, PropCreateRoomReq},
110 {DefSucsGetRoomsResp, PropGetRoomsResp},
111 {DefSucsCreateRoomResp, PropCreateRoomResp},
112 {DefSucsGetRoomWithIdResp, PropGetRoomWithIdResp},
113 {DefSucsGetRoomItemWithIdResp, PropItemGetRoomWithIdResp}
114 ],
115
116 %% Add definitions
117 46 lists:foreach(
118 fun({Definition, DefinitionProperties}) ->
119 230 cowboy_swagger:add_definition(Definition, DefinitionProperties)
120 end, DefinitionsAndProperties),
121
122 %% Request Body
123 46 RequestBodyCreateRoom = #{
124 in => body,
125 name => <<"room">>,
126 type => <<"object">>,
127 description => <<"Creates a room">>,
128 required => true,
129 schema => cowboy_swagger:schema(DefCreateRoomReq)
130 },
131
132 %% Pushs
133 46 RequestPushRoomId = #{
134 in => path,
135 name => <<"id">>,
136 type => <<"string">>,
137 description => <<"The ID of a room">>,
138 default => <<"1575-564351-207767">>,
139 required => true
140 },
141
142 %% Success responses
143 46 SucsGetRooms = #{
144 type => <<"array">>,
145 items => #{
146 type => <<"object">>,
147 schema => cowboy_swagger:schema(DefSucsGetRoomsResp)
148 }
149 },
150
151 %% Meta data
152 46 MetadataClientApiRoom = #{
153 get => #{
154 tags => ["Rooms"],
155 description => <<"Returns a list of rooms to which the user has subscribed.">>,
156 produces => ["application/json"],
157 responses => #{
158 ?HTTP_200_OK => #{description => <<"OK">>, schema => SucsGetRooms},
159 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
160 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
161 }
162 },
163 post => #{
164 tags => ["Rooms"],
165 description => <<"Creates a room.">>,
166 consumes => ["application/json"],
167 produces => ["application/json"],
168 parameters => [RequestBodyCreateRoom],
169 responses => #{
170 ?HTTP_200_OK => #{description => <<"OK">>, schema => cowboy_swagger:schema(DefSucsCreateRoomResp)},
171 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
172 ?HTTP_404_NOT_FOUND => #{description => <<"Not found">>},
173 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
174 }
175 }
176 },
177
178 46 MetadataClientApiRoomWithId = #{
179 get => #{
180 tags => ["Rooms"],
181 description => <<"Returns room's details.">>,
182 produces => ["application/json"],
183 parameters => [RequestPushRoomId],
184 responses => #{
185 ?HTTP_200_OK => #{description => <<"OK">>, schema => cowboy_swagger:schema(DefSucsGetRoomWithIdResp)},
186 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
187 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
188 }
189 },
190 put => #{
191 tags => ["Rooms"],
192 description => <<"Creates a room with the given ID.">>,
193 consumes => ["application/json"],
194 produces => ["application/json"],
195 parameters => [RequestPushRoomId, RequestBodyCreateRoom],
196 responses => #{
197 ?HTTP_201_CREATED => #{description => <<"Created">>, schema => cowboy_swagger:schema(DefSucsCreateRoomResp)},
198 ?HTTP_401_UNAUTHORIZED => #{description => <<"Unauthorized">>},
199 ?HTTP_404_NOT_FOUND => #{description => <<"Not found">>},
200 ?HTTP_500_INTERNAL_SERVER_ERROR => #{description => <<"Internal Server Error">>}
201 }
202 }
203 },
204
205 %% Paths
206 46 PathClientApiRooms = "/api/rooms",
207 46 PathClientApiRoomsWithId = "/api/rooms/[:id]",
208
209 %% Options
210 46 StoreOptions = [
211 {PathClientApiRooms, #{path => PathClientApiRooms}, MetadataClientApiRoom, mongoose_client_api_rooms},
212 {PathClientApiRoomsWithId, #{path => PathClientApiRoomsWithId}, MetadataClientApiRoomWithId, mongoose_client_api_rooms}
213 ],
214
215 %% Trail all data
216 46 [trails:trail(Path, Module, Options, Metadata) || {Path, Options, Metadata, Module} <- StoreOptions].
Line Hits Source