Browse Source

added swagger.yaml for documenting the api

mrkvon 4 years ago
parent
commit
add224975a
2 changed files with 382 additions and 2 deletions
  1. 41
    2
      README.md
  2. 341
    0
      swagger.yaml

+ 41
- 2
README.md View File

@@ -2,6 +2,45 @@
2 2
 
3 3
 [![Build Status](https://travis-ci.org/ditup/ditapi.svg?branch=master)](https://travis-ci.org/ditup/ditapi)
4 4
 
5
-REST api for ditup
5
+REST API for [ditup](http://ditup.org). The web app for the API is based [here](https://github.com/ditup/ditapp).
6 6
 
7
-JSON API
7
+Follows [JSON API](http://jsonapi.org) specification.
8
+
9
+## Prerequisities
10
+
11
+- Node.js v7.0.1 or later. We use cutting-edge EcmaScript features like [async functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function), which are supported since [v7.0.1](http://node.green/#async-functions).
12
+- npm v?
13
+- Arangodb v3.0 or later
14
+- maildev
15
+- @todo
16
+
17
+## Install
18
+
19
+- @todo
20
+- fork this repository
21
+- `cd` to the folder of this repository
22
+- run `npm install`
23
+
24
+## Run
25
+
26
+```bash
27
+NODE_ENV=development npm start
28
+```
29
+
30
+## Test
31
+
32
+```bash
33
+npm run test:watch
34
+```
35
+
36
+## Technology
37
+### Database
38
+[Arangodb](http://arangodb.com) is _a multi-model NOSQL database_. A model we are particularly interested in is _graphs_. They enable a nice way to model and navigate relationships.
39
+
40
+## Documentation
41
+
42
+[API documentation](apidoc.apib) written with [API Blueprint](https://apiblueprint.org)
43
+
44
+## Development
45
+
46
+If you want to collaborate on the creation of ditup, let's get in touch.

+ 341
- 0
swagger.yaml View File

@@ -0,0 +1,341 @@
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