Skip to content

Commit 2c82e64

Browse files
david-roccadavid-rocca
committed
Adding documentation for conversations
1 parent e726508 commit 2c82e64

3 files changed

Lines changed: 327 additions & 0 deletions

File tree

‎schemas/conversation/conversation.json‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://cve.mitre.org/schema/conversation/conversation.json",
4+
"type": "object",
5+
"title": "Conversation",
6+
"description": "JSON Schema for a conversation message",
7+
"properties": {
8+
"UUID": {
9+
"type": "string",
10+
"description": "Unique identifier for the conversation message"
11+
},
12+
"target_uuid": {
13+
"type": "string",
14+
"description": "UUID of the target entity (e.g., Organization)"
15+
},
16+
"previous_conversation_uuid": {
17+
"type": "string",
18+
"description": "UUID of the previous message in the conversation thread"
19+
},
20+
"next_conversation_uuid": {
21+
"type": "string",
22+
"description": "UUID of the next message in the conversation thread"
23+
},
24+
"author_id": {
25+
"type": "string",
26+
"description": "UUID of the message author"
27+
},
28+
"author_name": {
29+
"type": "string",
30+
"description": "Name of the message author"
31+
},
32+
"author_role": {
33+
"type": "string",
34+
"description": "Role of the message author"
35+
},
36+
"visibility": {
37+
"type": "string",
38+
"description": "Visibility level of the message"
39+
},
40+
"body": {
41+
"type": "string",
42+
"description": "Content of the message"
43+
},
44+
"posted_at": {
45+
"type": "string",
46+
"format": "date-time",
47+
"description": "Timestamp when the message was posted"
48+
},
49+
"last_updated": {
50+
"type": "string",
51+
"format": "date-time",
52+
"description": "Timestamp when the message was last updated"
53+
}
54+
},
55+
"required": [
56+
"UUID",
57+
"target_uuid",
58+
"author_id",
59+
"author_name",
60+
"body",
61+
"posted_at"
62+
]
63+
}

‎schemas/conversation/list-conversations-response.json‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"$id": "https://cve.mitre.org/schema/conversation/list-conversations-response.json",
4+
"type": "object",
5+
"title": "List Conversations Response",
6+
"description": "JSON Schema for a list of conversation messages",
7+
"properties": {
8+
"totalCount": {
9+
"type": "integer",
10+
"description": "Total number of items"
11+
},
12+
"itemsPerPage": {
13+
"type": "integer",
14+
"description": "Number of items per page"
15+
},
16+
"pageCount": {
17+
"type": "integer",
18+
"description": "Total number of pages"
19+
},
20+
"currentPage": {
21+
"type": "integer",
22+
"description": "Current page number"
23+
},
24+
"prevPage": {
25+
"type": ["integer", "null"],
26+
"description": "Previous page number"
27+
},
28+
"nextPage": {
29+
"type": ["integer", "null"],
30+
"description": "Next page number"
31+
},
32+
"conversations": {
33+
"type": "array",
34+
"items": {
35+
"$ref": "conversation.json"
36+
},
37+
"description": "List of conversation messages"
38+
}
39+
}
40+
}

‎src/controller/conversation.controller/index.js‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,76 @@ const CONSTANTS = getConstants()
77

88
// Get all conversations - SEC only
99
router.get('/conversation',
10+
/*
11+
#swagger.tags = ['Conversation']
12+
#swagger.operationId = 'getAllConversations'
13+
#swagger.summary = "Retrieves all conversations (accessible to Secretariat only)"
14+
#swagger.description = "
15+
<h2>Access Control</h2>
16+
<p>User must belong to an organization with the <b>Secretariat</b> role</p>
17+
<h2>Expected Behavior</h2>
18+
<p><b>Secretariat:</b> Retrieves all conversations</p>"
19+
#swagger.parameters['page'] = {
20+
in: 'query',
21+
description: 'The page of the conversation to retrieve',
22+
type: 'integer'
23+
}
24+
#swagger.parameters['$ref'] = [
25+
'#/components/parameters/apiEntityHeader',
26+
'#/components/parameters/apiUserHeader',
27+
'#/components/parameters/apiSecretHeader'
28+
]
29+
#swagger.responses[200] = {
30+
description: 'Returns all conversations, along with pagination fields if results span multiple pages of data',
31+
content: {
32+
"application/json": {
33+
schema: {
34+
$ref: '../schemas/conversation/list-conversations-response.json'
35+
}
36+
}
37+
}
38+
}
39+
#swagger.responses[400] = {
40+
description: 'Bad Request',
41+
content: {
42+
"application/json": {
43+
schema: { $ref: '../schemas/errors/bad-request.json' }
44+
}
45+
}
46+
}
47+
#swagger.responses[401] = {
48+
description: 'Not Authenticated',
49+
content: {
50+
"application/json": {
51+
schema: { $ref: '../schemas/errors/generic.json' }
52+
}
53+
}
54+
}
55+
#swagger.responses[403] = {
56+
description: 'Forbidden',
57+
content: {
58+
"application/json": {
59+
schema: { $ref: '../schemas/errors/generic.json' }
60+
}
61+
}
62+
}
63+
#swagger.responses[404] = {
64+
description: 'Not Found',
65+
content: {
66+
"application/json": {
67+
schema: { $ref: '../schemas/errors/generic.json' }
68+
}
69+
}
70+
}
71+
#swagger.responses[500] = {
72+
description: 'Internal Server Error',
73+
content: {
74+
"application/json": {
75+
schema: { $ref: '../schemas/errors/generic.json' }
76+
}
77+
}
78+
}
79+
*/
1080
mw.validateUser,
1181
mw.onlySecretariat,
1282
query().custom((query) => { return mw.validateQueryParameterNames(query, ['page']) }),
@@ -17,6 +87,77 @@ router.get('/conversation',
1787

1888
// Get all conversations for target UUID - SEC only
1989
router.get('/conversation/target/:uuid',
90+
/*
91+
#swagger.tags = ['Conversation']
92+
#swagger.operationId = 'getConversationsForTargetUUID'
93+
#swagger.summary = "Retrieves all conversations for a specific target UUID (accessible to Secretariat only)"
94+
#swagger.description = "
95+
<h2>Access Control</h2>
96+
<p>User must belong to an organization with the <b>Secretariat</b> role</p>
97+
<h2>Expected Behavior</h2>
98+
<p><b>Secretariat:</b> Retrieves all conversations for the specified target UUID</p>"
99+
#swagger.parameters['uuid'] = { description: 'The UUID of the target entity' }
100+
#swagger.parameters['page'] = {
101+
in: 'query',
102+
description: 'The page of the conversation to retrieve',
103+
type: 'integer'
104+
}
105+
#swagger.parameters['$ref'] = [
106+
'#/components/parameters/apiEntityHeader',
107+
'#/components/parameters/apiUserHeader',
108+
'#/components/parameters/apiSecretHeader'
109+
]
110+
#swagger.responses[200] = {
111+
description: 'Returns all conversations for the target UUID, along with pagination fields if results span multiple pages of data',
112+
content: {
113+
"application/json": {
114+
schema: {
115+
$ref: '../schemas/conversation/list-conversations-response.json'
116+
}
117+
}
118+
}
119+
}
120+
#swagger.responses[400] = {
121+
description: 'Bad Request',
122+
content: {
123+
"application/json": {
124+
schema: { $ref: '../schemas/errors/bad-request.json' }
125+
}
126+
}
127+
}
128+
#swagger.responses[401] = {
129+
description: 'Not Authenticated',
130+
content: {
131+
"application/json": {
132+
schema: { $ref: '../schemas/errors/generic.json' }
133+
}
134+
}
135+
}
136+
#swagger.responses[403] = {
137+
description: 'Forbidden',
138+
content: {
139+
"application/json": {
140+
schema: { $ref: '../schemas/errors/generic.json' }
141+
}
142+
}
143+
}
144+
#swagger.responses[404] = {
145+
description: 'Not Found',
146+
content: {
147+
"application/json": {
148+
schema: { $ref: '../schemas/errors/generic.json' }
149+
}
150+
}
151+
}
152+
#swagger.responses[500] = {
153+
description: 'Internal Server Error',
154+
content: {
155+
"application/json": {
156+
schema: { $ref: '../schemas/errors/generic.json' }
157+
}
158+
}
159+
}
160+
*/
20161
mw.validateUser,
21162
mw.onlySecretariat,
22163
query().custom((query) => { return mw.validateQueryParameterNames(query, ['page']) }),
@@ -27,6 +168,89 @@ router.get('/conversation/target/:uuid',
27168

28169
// Post conversation for target UUID - SEC only
29170
router.post('/conversation/target/:uuid',
171+
/*
172+
#swagger.tags = ['Conversation']
173+
#swagger.operationId = 'createConversationForTargetUUID'
174+
#swagger.summary = "Creates a conversation for a specific target UUID (accessible to Secretariat only)"
175+
#swagger.description = "
176+
<h2>Access Control</h2>
177+
<p>User must belong to an organization with the <b>Secretariat</b> role</p>
178+
<h2>Expected Behavior</h2>
179+
<p><b>Secretariat:</b> Creates a conversation for the specified target UUID</p>"
180+
#swagger.parameters['uuid'] = { description: 'The UUID of the target entity' }
181+
#swagger.parameters['$ref'] = [
182+
'#/components/parameters/apiEntityHeader',
183+
'#/components/parameters/apiUserHeader',
184+
'#/components/parameters/apiSecretHeader'
185+
]
186+
#swagger.requestBody = {
187+
required: true,
188+
content: {
189+
'application/json': {
190+
schema: {
191+
type: 'object',
192+
properties: {
193+
body: {
194+
type: 'string',
195+
description: 'The content of the conversation message'
196+
}
197+
},
198+
required: ['body']
199+
}
200+
}
201+
}
202+
}
203+
#swagger.responses[200] = {
204+
description: 'Returns the created conversation',
205+
content: {
206+
"application/json": {
207+
schema: {
208+
$ref: '../schemas/conversation/conversation.json'
209+
}
210+
}
211+
}
212+
}
213+
#swagger.responses[400] = {
214+
description: 'Bad Request',
215+
content: {
216+
"application/json": {
217+
schema: { $ref: '../schemas/errors/bad-request.json' }
218+
}
219+
}
220+
}
221+
#swagger.responses[401] = {
222+
description: 'Not Authenticated',
223+
content: {
224+
"application/json": {
225+
schema: { $ref: '../schemas/errors/generic.json' }
226+
}
227+
}
228+
}
229+
#swagger.responses[403] = {
230+
description: 'Forbidden',
231+
content: {
232+
"application/json": {
233+
schema: { $ref: '../schemas/errors/generic.json' }
234+
}
235+
}
236+
}
237+
#swagger.responses[404] = {
238+
description: 'Not Found',
239+
content: {
240+
"application/json": {
241+
schema: { $ref: '../schemas/errors/generic.json' }
242+
}
243+
}
244+
}
245+
#swagger.responses[500] = {
246+
description: 'Internal Server Error',
247+
content: {
248+
"application/json": {
249+
schema: { $ref: '../schemas/errors/generic.json' }
250+
}
251+
}
252+
}
253+
*/
30254
mw.validateUser,
31255
mw.onlySecretariat,
32256
param(['uuid']).isUUID(4),

0 commit comments

Comments
 (0)