swagger.yaml 7.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. ---
  2. # this is an API for ditup.org/api
  3. # the repository https://github.com/ditup/ditapi
  4. swagger: "2.0"
  5. info:
  6. title: ditup API
  7. description: the REST JSON API for ditup.org online platform for real-world collaboration
  8. version: "1.0.0"
  9. # the domain of the service
  10. host: ditup.org
  11. # array of all schemes that your API supports
  12. schemes:
  13. - http
  14. - https
  15. # will be prefixed to all paths
  16. basePath: /api
  17. securityDefinitions:
  18. basicAuth:
  19. type: basic
  20. description: HTTP Basic Authentication
  21. consumes:
  22. - application/vnd.api+json
  23. produces:
  24. - application/vnd.api+json
  25. paths:
  26. # CRUD users
  27. /users:
  28. get:
  29. tags:
  30. - users
  31. summary: users
  32. description: The users collection
  33. security:
  34. - basicAuth: []
  35. responses:
  36. 200:
  37. description: An array of users
  38. schema:
  39. type: array
  40. items:
  41. $ref: '#/definitions/User'
  42. default:
  43. description: Unexpected error
  44. schema:
  45. $ref: '#/definitions/Error'
  46. post:
  47. tags:
  48. - users
  49. description: Create a new user
  50. security:
  51. - basicAuth: []
  52. parameters:
  53. - in: body
  54. name: body
  55. description:
  56. required: true
  57. schema:
  58. $ref: '#/definitions/NewUser'
  59. responses:
  60. 201:
  61. description: A new user
  62. schema:
  63. $ref: '#/definitions/User'
  64. /users/{username}:
  65. get:
  66. tags:
  67. - users
  68. description: get user by username
  69. security:
  70. - basicAuth: []
  71. parameters:
  72. - in: path
  73. name: username
  74. description: The username of the user we want to GET. Use user1 for testing.
  75. required: true
  76. type: string
  77. responses:
  78. 200:
  79. description: OK
  80. patch:
  81. tags:
  82. - users
  83. description: update the user data
  84. security:
  85. - basicAuth: []
  86. parameters:
  87. - in: path
  88. name: username
  89. description: The username of the user we want to GET. Use user1 for testing.
  90. required: true
  91. type: string
  92. - in: body
  93. name: body
  94. description: profile or settings parameter(s) to update. Must update only profile XOR settings XOR email
  95. required: true
  96. schema:
  97. $ref: '#/definitions/User'
  98. responses:
  99. 200:
  100. description: OK
  101. schema:
  102. $ref: '#/definitions/User'
  103. delete:
  104. tags:
  105. - users
  106. description: delete user by username
  107. security:
  108. - basicAuth: []
  109. parameters:
  110. - in: path
  111. name: username
  112. description: The username of the user we want to DELETE
  113. required: true
  114. type: string
  115. responses:
  116. 204:
  117. description: No Content
  118. # CRUD tags
  119. /tags:
  120. get:
  121. tags:
  122. - tags
  123. description: get list of tags (should be filtered by parameters)
  124. security:
  125. - basicAuth: []
  126. responses:
  127. 200:
  128. description: OK
  129. post:
  130. tags:
  131. - tags
  132. description: create a new tag
  133. security:
  134. - basicAuth: []
  135. parameters:
  136. - in: body
  137. name: body
  138. description: data for creating a new tag
  139. required: true
  140. schema:
  141. $ref: '#/definitions/NewTag'
  142. responses:
  143. 201:
  144. description: Created
  145. schema:
  146. $ref: '#/definitions/Tag'
  147. /tags/{tagname}:
  148. get:
  149. tags:
  150. - tags
  151. description: get a tag by tagname
  152. security:
  153. - basicAuth: []
  154. parameters:
  155. - in: path
  156. name: tagname
  157. description: The tagname of the tag to get
  158. required: true
  159. type: string
  160. responses:
  161. 200:
  162. description: OK
  163. schema:
  164. $ref: '#/definitions/Tag'
  165. 404:
  166. description: Not Found
  167. patch:
  168. tags:
  169. - tags
  170. description: update a tag
  171. parameters:
  172. - in: body
  173. name: body
  174. description: tag object with attributes to update
  175. required: true
  176. schema:
  177. $ref: '#/definitions/Tag'
  178. - in: path
  179. name: tagname
  180. description: The tagname of the tag to update
  181. required: true
  182. type: string
  183. responses:
  184. 200:
  185. description: OK
  186. schema:
  187. $ref: '#/definitions/Tag'
  188. 403:
  189. description: Not Authorized
  190. 404:
  191. description: Not Found
  192. delete:
  193. tags:
  194. - tags
  195. description: delete tag by tagname
  196. security:
  197. - basicAuth: []
  198. parameters:
  199. - in: path
  200. name: tagname
  201. description: The tagname of the tag we want to DELETE
  202. required: true
  203. type: string
  204. responses:
  205. 204:
  206. description: No Content
  207. 403:
  208. description: Not Authorized
  209. 404:
  210. description: Not Found
  211. definitions:
  212. User:
  213. type: object
  214. required:
  215. - data
  216. properties:
  217. data:
  218. type: object
  219. required:
  220. - id
  221. - type
  222. - attributes
  223. properties:
  224. id:
  225. type: string
  226. description: the username
  227. type:
  228. type: string
  229. enum:
  230. - users
  231. attributes:
  232. type: object
  233. required:
  234. - username
  235. properties:
  236. username:
  237. type: string
  238. description: description
  239. email:
  240. type: string
  241. description: description
  242. givenName:
  243. type: string
  244. description: description
  245. familyName:
  246. type: string
  247. description: description
  248. description:
  249. type: string
  250. description: description
  251. NewUser:
  252. type: object
  253. required:
  254. - data
  255. properties:
  256. data:
  257. type: object
  258. required:
  259. - type
  260. - attributes
  261. properties:
  262. type:
  263. type: string
  264. enum:
  265. - users
  266. attributes:
  267. type: object
  268. required:
  269. - username
  270. - email
  271. - password
  272. properties:
  273. username:
  274. type: string
  275. email:
  276. type: string
  277. password:
  278. type: string
  279. Tag:
  280. type: object
  281. required:
  282. - data
  283. properties:
  284. data:
  285. type: object
  286. required:
  287. - id
  288. - type
  289. - attributes
  290. properties:
  291. id:
  292. type: string
  293. description: a unique tagname of the tag
  294. type:
  295. type: string
  296. enum:
  297. - tags
  298. attributes:
  299. type: object
  300. required:
  301. - tagname
  302. - description
  303. properties:
  304. tagname:
  305. type: string
  306. description:
  307. type: string
  308. description: description of the tag
  309. NewTag:
  310. type: object
  311. required:
  312. - data
  313. properties:
  314. data:
  315. type: object
  316. required:
  317. - type
  318. - attributes
  319. properties:
  320. type:
  321. type: string
  322. enum:
  323. - tags
  324. attributes:
  325. type: object
  326. required:
  327. - tagname
  328. properties:
  329. tagname:
  330. type: string
  331. description:
  332. type: string
  333. Error:
  334. properties:
  335. code:
  336. type: integer
  337. format: int32
  338. message:
  339. type: string
  340. fields:
  341. type: string