Mercurial > prosody-modules
comparison mod_rest/res/openapi.yaml @ 4528:fd15e7f00ff5
mod_rest: Move openapi spec into res/ dir to get it included in rocks
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Tue, 23 Mar 2021 20:27:44 +0100 |
parents | mod_rest/openapi.yaml@9a6aaba3d5ef |
children | c6d44e1fb4d9 |
comparison
equal
deleted
inserted
replaced
4527:9a6aaba3d5ef | 4528:fd15e7f00ff5 |
---|---|
1 --- | |
2 openapi: 3.0.1 | |
3 | |
4 info: | |
5 title: mod_rest API | |
6 version: 0.3.2 | |
7 description: | | |
8 API for sending and receiving stanzas, in a REST-ish fashion or by | |
9 responding to webhooks. Multiple formats supported, including native XML | |
10 and a simplified JSON mapping. | |
11 license: | |
12 name: MIT | |
13 | |
14 paths: | |
15 | |
16 /rest: | |
17 post: | |
18 summary: Send stanzas and receive responses. Webhooks work the same way. | |
19 tags: | |
20 - generic | |
21 security: | |
22 - basic: [] | |
23 - token: [] | |
24 requestBody: | |
25 $ref: '#/components/requestBodies/common' | |
26 responses: | |
27 200: | |
28 $ref: '#/components/responses/success' | |
29 202: | |
30 $ref: '#/components/responses/sent' | |
31 | |
32 /rest/{kind}/{type}/{to}: | |
33 post: | |
34 summary: Even more RESTful mapping with certain components in the path. | |
35 tags: | |
36 - generic | |
37 security: | |
38 - basic: [] | |
39 - token: [] | |
40 parameters: | |
41 - $ref: '#/components/parameters/kind' | |
42 - $ref: '#/components/parameters/type' | |
43 - $ref: '#/components/parameters/to' | |
44 requestBody: | |
45 $ref: '#/components/requestBodies/common' | |
46 responses: | |
47 200: | |
48 $ref: '#/components/responses/success' | |
49 | |
50 /rest/ping/{to}: | |
51 get: | |
52 tags: | |
53 - query | |
54 summary: Ping a local or remote server or other entity | |
55 security: | |
56 - basic: [] | |
57 - token: [] | |
58 parameters: | |
59 - $ref: '#/components/parameters/to' | |
60 responses: | |
61 200: | |
62 description: Test reachability of some address | |
63 content: | |
64 application/json: | |
65 schema: | |
66 $ref: '#/components/schemas/iq_pong' | |
67 application/xmpp+xml: | |
68 schema: | |
69 $ref: '#/components/schemas/iq_pong' | |
70 | |
71 | |
72 /rest/version/{to}: | |
73 get: | |
74 tags: | |
75 - query | |
76 summary: Ask what software version is used. | |
77 security: | |
78 - basic: [] | |
79 - token: [] | |
80 parameters: | |
81 - $ref: '#/components/parameters/to' | |
82 responses: | |
83 200: | |
84 description: Version query response | |
85 content: | |
86 application/json: | |
87 schema: | |
88 $ref: '#/components/schemas/iq_result_version' | |
89 application/xmpp+xml: | |
90 schema: | |
91 $ref: '#/components/schemas/iq_result_version' | |
92 | |
93 /rest/disco/{to}: | |
94 get: | |
95 tags: | |
96 - query | |
97 summary: Query a remote entity for supported features | |
98 security: | |
99 - basic: [] | |
100 - token: [] | |
101 parameters: | |
102 - $ref: '#/components/parameters/to' | |
103 responses: | |
104 200: | |
105 $ref: '#/components/responses/success' | |
106 | |
107 /rest/items/{to}: | |
108 get: | |
109 tags: | |
110 - query | |
111 summary: Query an entity for related services, chat rooms or other items | |
112 security: | |
113 - basic: [] | |
114 - token: [] | |
115 parameters: | |
116 - $ref: '#/components/parameters/to' | |
117 responses: | |
118 200: | |
119 $ref: '#/components/responses/success' | |
120 | |
121 components: | |
122 schemas: | |
123 stanza: | |
124 type: object | |
125 example: | |
126 body: Hello | |
127 type: chat | |
128 kind: message | |
129 to: alice@example.com | |
130 state: active | |
131 | |
132 properties: | |
133 kind: | |
134 $ref: '#/components/schemas/kind' | |
135 type: | |
136 $ref: '#/components/schemas/type' | |
137 to: | |
138 $ref: '#/components/schemas/to' | |
139 from: | |
140 $ref: '#/components/schemas/from' | |
141 id: | |
142 $ref: '#/components/schemas/id' | |
143 lang: | |
144 $ref: '#/components/schemas/lang' | |
145 | |
146 body: | |
147 $ref: '#/components/schemas/body' | |
148 subject: | |
149 $ref: '#/components/schemas/subject' | |
150 thread: | |
151 $ref: '#/components/schemas/thread' | |
152 | |
153 show: | |
154 $ref: '#/components/schemas/show' | |
155 status: | |
156 $ref: '#/components/schemas/status' | |
157 priority: | |
158 $ref: '#/components/schemas/priority' | |
159 | |
160 state: | |
161 $ref: '#/components/schemas/state' | |
162 nick: | |
163 $ref: '#/components/schemas/nick' | |
164 delay: | |
165 $ref: '#/components/schemas/delay' | |
166 replace: | |
167 $ref: '#/components/schemas/replace' | |
168 | |
169 join: | |
170 $ref: '#/components/schemas/join' | |
171 | |
172 html: | |
173 $ref: '#/components/schemas/html' | |
174 | |
175 ping: | |
176 $ref: '#/components/schemas/ping' | |
177 version: | |
178 $ref: '#/components/schemas/version' | |
179 disco: | |
180 $ref: '#/components/schemas/disco' | |
181 items: | |
182 $ref: '#/components/schemas/items' | |
183 command: | |
184 $ref: '#/components/schemas/command' | |
185 | |
186 oob_url: | |
187 $ref: '#/components/schemas/oob_url' | |
188 payload: | |
189 $ref: '#/components/schemas/payload' | |
190 dataform: | |
191 $ref: '#/components/schemas/dataform' | |
192 formdata: | |
193 $ref: '#/components/schemas/formdata' | |
194 stats: | |
195 $ref: '#/components/schemas/stats' | |
196 error: | |
197 $ref: '#/components/schemas/error' | |
198 | |
199 iq_pong: | |
200 description: Test reachability of some XMPP address | |
201 type: object | |
202 xml: | |
203 name: iq | |
204 properties: | |
205 type: | |
206 type: string | |
207 enum: | |
208 - result | |
209 xml: | |
210 attribute: true | |
211 | |
212 iq_result_version: | |
213 description: Version query response | |
214 type: object | |
215 xml: | |
216 name: iq | |
217 properties: | |
218 type: | |
219 type: string | |
220 enum: | |
221 - result | |
222 xml: | |
223 attribute: true | |
224 version: | |
225 $ref: '#/components/schemas/version' | |
226 | |
227 kind: | |
228 description: Which kind of stanza | |
229 type: string | |
230 enum: | |
231 - message | |
232 - presence | |
233 - iq | |
234 | |
235 type: | |
236 description: Stanza type | |
237 type: string | |
238 enum: | |
239 - chat | |
240 - normal | |
241 - headline | |
242 - groupchat | |
243 - get | |
244 - set | |
245 - result | |
246 - available | |
247 - unavailable | |
248 - subscribe | |
249 - subscribed | |
250 - unsubscribe | |
251 - unsubscribed | |
252 | |
253 to: | |
254 description: recipient | |
255 example: alice@example.com | |
256 type: string | |
257 | |
258 from: | |
259 description: the sender | |
260 example: bob@localhost.example | |
261 type: string | |
262 | |
263 id: | |
264 description: Reasonably unique id. mod_rest generates one if left out. | |
265 type: string | |
266 | |
267 lang: | |
268 description: Language code | |
269 example: en | |
270 type: string | |
271 | |
272 body: | |
273 description: Human-readable chat message | |
274 example: Hello, World! | |
275 type: string | |
276 | |
277 subject: | |
278 description: Subject of message or group chat | |
279 example: Talking about stuff | |
280 type: string | |
281 | |
282 thread: | |
283 description: Message thread identifier | |
284 type: string | |
285 | |
286 show: | |
287 description: indicator of availability, ie away or not | |
288 type: string | |
289 enum: | |
290 - away | |
291 - chat | |
292 - dnd | |
293 - xa | |
294 | |
295 status: | |
296 description: Textual status message. | |
297 type: string | |
298 | |
299 priority: | |
300 description: Presence priority | |
301 type: string | |
302 | |
303 state: | |
304 description: Chat state notifications, e.g. "is typing..." | |
305 type: string | |
306 enum: | |
307 - active | |
308 - inactive | |
309 - gone | |
310 - composing | |
311 - paused | |
312 example: composing | |
313 | |
314 nick: | |
315 type: string | |
316 description: Nickname of the sender | |
317 | |
318 delay: | |
319 type: string | |
320 description: Timestamp of when a stanza was delayed, in ISO 8601 / XEP-0082 | |
321 format. | |
322 | |
323 replace: | |
324 type: string | |
325 description: ID of message being replaced (e.g. for corrections) | |
326 | |
327 join: | |
328 description: For joining Multi-User-Chats | |
329 type: boolean | |
330 enum: | |
331 - true | |
332 | |
333 html: | |
334 description: HTML version of 'body' | |
335 example: <body><p>Hello!</p></body> | |
336 type: string | |
337 | |
338 ping: | |
339 description: A ping. | |
340 type: boolean | |
341 enum: | |
342 - true | |
343 xml: | |
344 name: ping | |
345 namespace: urn:xmpp:ping | |
346 | |
347 version: | |
348 type: object | |
349 description: Software version query | |
350 properties: | |
351 name: | |
352 type: string | |
353 example: My Software | |
354 version: | |
355 type: string | |
356 example: 1.0.0 | |
357 os: | |
358 type: string | |
359 example: Linux | |
360 required: | |
361 - name | |
362 - version | |
363 xml: | |
364 name: query | |
365 namespace: jabber:iq:version | |
366 | |
367 disco: | |
368 description: Discover supported features | |
369 oneOf: | |
370 - description: A full response | |
371 type: object | |
372 properties: | |
373 features: | |
374 description: List of URIs indicating supported features | |
375 type: array | |
376 items: | |
377 type: string | |
378 identities: | |
379 description: List of abstract identities or types that describe the | |
380 entity | |
381 type: array | |
382 example: | |
383 - name: Prosody | |
384 type: im | |
385 category: server | |
386 items: | |
387 type: object | |
388 properties: | |
389 name: | |
390 type: string | |
391 type: | |
392 type: string | |
393 category: | |
394 type: string | |
395 node: | |
396 type: string | |
397 extensions: | |
398 type: object | |
399 - description: A query with a node, or an empty response with a node | |
400 type: string | |
401 - description: Either a query, or an empty response | |
402 type: boolean | |
403 | |
404 items: | |
405 description: List of references to other entities | |
406 oneOf: | |
407 - description: List of items referenced | |
408 type: array | |
409 items: | |
410 properties: | |
411 jid: | |
412 type: string | |
413 description: Address of item | |
414 node: | |
415 type: string | |
416 name: | |
417 type: string | |
418 description: Descriptive name | |
419 required: | |
420 - jid | |
421 type: object | |
422 - type: string | |
423 description: A query with a node, or an empty reply list with a node | |
424 - description: An items query or empty list | |
425 type: boolean | |
426 enum: | |
427 - true | |
428 | |
429 command: | |
430 description: Ad-hoc commands. | |
431 oneOf: | |
432 - type: object | |
433 properties: | |
434 data: | |
435 $ref: '#/components/schemas/formdata' | |
436 action: | |
437 type: string | |
438 note: | |
439 type: object | |
440 properties: | |
441 text: | |
442 type: string | |
443 type: | |
444 type: string | |
445 enum: | |
446 - info | |
447 - warn | |
448 - error | |
449 form: | |
450 $ref: '#/components/schemas/dataform' | |
451 sessionid: | |
452 type: string | |
453 status: | |
454 type: string | |
455 node: | |
456 type: string | |
457 actions: | |
458 type: object | |
459 properties: | |
460 complete: | |
461 type: boolean | |
462 prev: | |
463 type: boolean | |
464 next: | |
465 type: boolean | |
466 execute: | |
467 type: string | |
468 - type: string | |
469 description: Call a command by 'node' id, without arguments | |
470 | |
471 oob_url: | |
472 description: URL of an attached media file. | |
473 example: https://media.example.net/thisfile.jpg | |
474 type: string | |
475 | |
476 payload: | |
477 description: A piece of arbitrary JSON with a type field attached | |
478 type: object | |
479 required: | |
480 - datatype | |
481 - data | |
482 properties: | |
483 data: | |
484 example: '{"some":"json"}' | |
485 type: object | |
486 datatype: | |
487 example: urn:example:my-json#payload | |
488 type: string | |
489 | |
490 dataform: | |
491 description: Data form | |
492 type: object | |
493 properties: | |
494 title: | |
495 description: Title of the form | |
496 example: TPS Report | |
497 type: string | |
498 fields: | |
499 type: array | |
500 items: | |
501 description: Form field | |
502 type: object | |
503 properties: | |
504 value: | |
505 description: Field value | |
506 oneOf: | |
507 - type: string | |
508 - type: array | |
509 items: | |
510 type: string | |
511 type: | |
512 description: Type of form field | |
513 type: string | |
514 label: | |
515 description: Descriptive label for the field | |
516 type: string | |
517 desc: | |
518 description: Longer description, i.e. that would go in a tooltip | |
519 type: string | |
520 required: | |
521 description: Whether the field must be included in the form | |
522 type: boolean | |
523 var: | |
524 description: Internal name of the field | |
525 type: string | |
526 type: | |
527 type: string | |
528 enum: | |
529 - form | |
530 - submit | |
531 - cancel | |
532 - result | |
533 instructions: | |
534 type: string | |
535 | |
536 formdata: | |
537 description: Simplified data form carrying only values | |
538 type: object | |
539 additionalProperties: | |
540 oneOf: | |
541 - type: string | |
542 - type: array | |
543 items: | |
544 type: string | |
545 | |
546 stats: | |
547 description: Statistics | |
548 type: array | |
549 items: | |
550 type: object | |
551 properties: | |
552 name: | |
553 type: string | |
554 unit: | |
555 type: string | |
556 value: | |
557 type: string | |
558 | |
559 error: | |
560 description: Description of something gone wrong. See the Stanza Errors section in RFC 6120. | |
561 type: object | |
562 properties: | |
563 type: | |
564 description: General category of error | |
565 type: string | |
566 enum: | |
567 - auth | |
568 - cancel | |
569 - continue | |
570 - modify | |
571 - wait | |
572 condition: | |
573 description: Specific error condition. | |
574 type: string | |
575 # enum: [ full list available in RFC 6120 ] | |
576 code: | |
577 description: Legacy numeric error code. Similar to HTTP status codes. | |
578 type: integer | |
579 text: | |
580 description: Description of error intended for human eyes. | |
581 type: string | |
582 | |
583 securitySchemes: | |
584 token: | |
585 description: Tokens from mod_http_oauth2. | |
586 scheme: Bearer | |
587 type: http | |
588 basic: | |
589 description: Use JID as username. | |
590 scheme: Basic | |
591 type: http | |
592 | |
593 requestBodies: | |
594 common: | |
595 required: true | |
596 content: | |
597 application/json: | |
598 schema: | |
599 $ref: '#/components/schemas/stanza' | |
600 application/xmpp+xml: | |
601 schema: | |
602 description: Single XMPP stanza in XML format. | |
603 application/x-www-form-urlencoded: | |
604 schema: | |
605 description: A subset of the JSON schema, only top level string fields. | |
606 | |
607 responses: | |
608 success: | |
609 description: The stanza was sent and returned a response. | |
610 content: | |
611 application/json: | |
612 schema: | |
613 $ref: '#/components/schemas/stanza' | |
614 application/xmpp+xml: | |
615 schema: | |
616 description: Single XMPP stanza in XML format. | |
617 example: <message><body>Hello</body></message> | |
618 application/x-www-form-urlencoded: | |
619 schema: | |
620 description: A subset of the JSON schema, only top level string fields. | |
621 example: body=Hello | |
622 text/plain: | |
623 schema: | |
624 description: Plain text response used as message body. | |
625 example: Hello | |
626 type: string | |
627 sent: | |
628 description: The stanza was sent without problem, and without response, | |
629 so an empty reply. | |
630 | |
631 parameters: | |
632 to: | |
633 name: to | |
634 in: path | |
635 required: true | |
636 schema: | |
637 $ref: '#/components/schemas/to' | |
638 kind: | |
639 name: kind | |
640 in: path | |
641 required: true | |
642 schema: | |
643 $ref: '#/components/schemas/kind' | |
644 type: | |
645 name: type | |
646 in: path | |
647 required: true | |
648 schema: | |
649 $ref: '#/components/schemas/type' | |
650 | |
651 ... |