Browse Source

Merge pull request #82 from tracim/fix/better_api_doc

Bastien Sevajol 6 years ago
parent
commit
1821eeacfd
No account linked to committer's email

+ 0 - 2
tracim/tests/functional/test_session.py View File

@@ -50,7 +50,6 @@ class TestLoginEndpoint(FunctionalTest):
50 50
         assert res.json_body['created']
51 51
         assert res.json_body['is_active']
52 52
         assert res.json_body['profile']
53
-        assert isinstance(res.json_body['profile']['id'], int)
54 53
         assert res.json_body['profile']['slug'] == 'administrators'
55 54
         assert res.json_body['caldav_url'] is None
56 55
         assert res.json_body['avatar_url'] is None
@@ -109,7 +108,6 @@ class TestWhoamiEndpoint(FunctionalTest):
109 108
         assert res.json_body['created']
110 109
         assert res.json_body['is_active']
111 110
         assert res.json_body['profile']
112
-        assert isinstance(res.json_body['profile']['id'], int)
113 111
         assert res.json_body['profile']['slug'] == 'administrators'
114 112
         assert res.json_body['caldav_url'] is None
115 113
         assert res.json_body['avatar_url'] is None

+ 0 - 1
tracim/tests/functional/test_workspaces.py View File

@@ -156,7 +156,6 @@ class TestWorkspaceMembersEndpoint(FunctionalTest):
156 156
         assert len(res) == 2
157 157
         user_role = res[0]
158 158
         assert user_role['role_slug'] == 'workspace-manager'
159
-        assert user_role['role_id'] == 8
160 159
         assert user_role['user_id'] == 1
161 160
         assert user_role['workspace_id'] == 1
162 161
         assert user_role['user']['display_name'] == 'Global manager'

+ 113 - 32
tracim/views/core_api/schemas.py View File

@@ -9,44 +9,84 @@ from tracim.models.data import UserRoleInWorkspace
9 9
 
10 10
 
11 11
 class ProfileSchema(marshmallow.Schema):
12
-    id = marshmallow.fields.Int(dump_only=True, validate=OneOf(Profile._IDS))
13
-    slug = marshmallow.fields.String(attribute='name', validate=OneOf(Profile._NAME))
12
+    slug = marshmallow.fields.String(
13
+        attribute='name',
14
+        validate=OneOf(Profile._NAME),
15
+        example='managers',
16
+    )
17
+
18
+    class Meta:
19
+        description = 'User Profile, give user right on whole Tracim instance.'
14 20
 
15 21
 
16 22
 class UserSchema(marshmallow.Schema):
17 23
 
18
-    user_id = marshmallow.fields.Int(dump_only=True)
19
-    email = marshmallow.fields.Email(required=True)
20
-    display_name = marshmallow.fields.String()
21
-    created = marshmallow.fields.DateTime(format='iso8601')
22
-    is_active = marshmallow.fields.Bool()
24
+    user_id = marshmallow.fields.Int(dump_only=True, example=3)
25
+    email = marshmallow.fields.Email(
26
+        required=True,
27
+        example='suri.cate@algoo.fr'
28
+    )
29
+    display_name = marshmallow.fields.String(
30
+        example='Suri Cate',
31
+    )
32
+    created = marshmallow.fields.DateTime(
33
+        format='iso8601',
34
+        description='User account creation date (iso8601 format).',
35
+    )
36
+    is_active = marshmallow.fields.Bool(
37
+        example=True,
38
+         # TODO - G.M - Explains this value.
39
+    )
23 40
     # TODO - G.M - 17-04-2018 - Restrict timezone values
24
-    timezone = marshmallow.fields.String()
41
+    timezone = marshmallow.fields.String(
42
+        example="Paris/Europe",
43
+    )
25 44
     # TODO - G.M - 17-04-2018 - check this, relative url allowed ?
26 45
     caldav_url = marshmallow.fields.Url(
27 46
         allow_none=True,
28 47
         relative=True,
29
-        attribute='calendar_url'
48
+        attribute='calendar_url',
49
+        example="/api/v2/calendar/user/3.ics/",
50
+        description="The url for calendar CalDAV direct access",
51
+    )
52
+    avatar_url = marshmallow.fields.Url(
53
+        allow_none=True,
54
+        example="/api/v2/assets/avatars/suri-cate.jpg",
55
+        description="avatar_url is the url to the image file. "
56
+                    "If no avatar, then set it to null "
57
+                    "(and frontend will interpret this with a default avatar)",
30 58
     )
31
-    avatar_url = marshmallow.fields.Url(allow_none=True)
32 59
     profile = marshmallow.fields.Nested(
33 60
         ProfileSchema,
34 61
         many=False,
35 62
     )
36 63
 
64
+    class Meta:
65
+        description = 'User account of Tracim'
66
+
37 67
 
38 68
 class UserIdPathSchema(marshmallow.Schema):
39
-    user_id = marshmallow.fields.Int()
69
+    user_id = marshmallow.fields.Int(example=3)
40 70
 
41 71
 
42 72
 class WorkspaceIdPathSchema(marshmallow.Schema):
43
-    workspace_id = marshmallow.fields.Int()
73
+    workspace_id = marshmallow.fields.Int(example=4)
44 74
 
45 75
 
46 76
 class BasicAuthSchema(marshmallow.Schema):
47 77
 
48
-    email = marshmallow.fields.Email(required=True)
49
-    password = marshmallow.fields.String(required=True, load_only=True)
78
+    email = marshmallow.fields.Email(
79
+        example='suri.cate@algoo.fr',
80
+        required=True
81
+    )
82
+    password = marshmallow.fields.String(
83
+        example='8QLa$<w',
84
+        required=True,
85
+        load_only=True,
86
+    )
87
+
88
+    class Meta:
89
+        description = 'Entry for HTTP Basic Auth'
50 90
 
51 91
     @post_load
52 92
     def make_login(self, data):
@@ -58,40 +98,69 @@ class LoginOutputHeaders(marshmallow.Schema):
58 98
 
59 99
 
60 100
 class NoContentSchema(marshmallow.Schema):
101
+
102
+    class Meta:
103
+        description = 'Empty Schema'
61 104
     pass
62 105
 
63 106
 
64 107
 class WorkspaceMenuEntrySchema(marshmallow.Schema):
65
-    slug = marshmallow.fields.String()
66
-    label = marshmallow.fields.String()
67
-    route = marshmallow.fields.String()
68
-    hexcolor = marshmallow.fields.String()
69
-    fa_icon = marshmallow.fields.String()
108
+    slug = marshmallow.fields.String(example='markdown-pages')
109
+    label = marshmallow.fields.String(example='Markdown Documents')
110
+    route = marshmallow.fields.String(
111
+        example='/#/workspace/{workspace_id}/contents/?type=mardown-page',
112
+        description='the route is the frontend route. '
113
+                    'It may include workspace_id '
114
+                    'which must be replaced on backend size '
115
+                    '(the route must be ready-to-use)'
116
+    )
117
+    fa_icon = marshmallow.fields.String(
118
+        example='file-text-o',
119
+        description='CSS class of the icon. Example: file-o for using Fontawesome file-text-o icon',  # nopep8
120
+    )
121
+    hexcolor = marshmallow.fields.String(
122
+        example='#F0F9DC',
123
+        description='Hexadecimal color of the entry.'
124
+    )
125
+
126
+    class Meta:
127
+        description = 'Entry element of a workspace menu'
70 128
 
71 129
 
72 130
 class WorkspaceDigestSchema(marshmallow.Schema):
73
-    id = marshmallow.fields.Int()
74
-    label = marshmallow.fields.String()
131
+    id = marshmallow.fields.Int(example=4)
132
+    label = marshmallow.fields.String(example='Intranet')
75 133
     sidebar_entries = marshmallow.fields.Nested(
76 134
         WorkspaceMenuEntrySchema,
77 135
         many=True,
78 136
     )
79 137
 
138
+    class Meta:
139
+        description = 'Digest of workspace informations'
140
+
80 141
 
81 142
 class WorkspaceSchema(WorkspaceDigestSchema):
82
-    slug = marshmallow.fields.String()
83
-    description = marshmallow.fields.String()
143
+    slug = marshmallow.fields.String(example='intranet')
144
+    description = marshmallow.fields.String(example='All intranet data.')
145
+
146
+    class Meta:
147
+        description = 'Full workspace informations'
84 148
 
85 149
 
86 150
 class WorkspaceMemberSchema(marshmallow.Schema):
87
-    role_id = marshmallow.fields.Int(validate=OneOf(UserRoleInWorkspace.get_all_role_values()))  # nopep8
88
-    role_slug = marshmallow.fields.String(validate=OneOf(UserRoleInWorkspace.get_all_role_slug()))  # nopep8
89
-    user_id = marshmallow.fields.Int()
90
-    workspace_id = marshmallow.fields.Int()
151
+    role_slug = marshmallow.fields.String(
152
+        example='contributor',
153
+        validate=OneOf(UserRoleInWorkspace.get_all_role_slug())
154
+    )
155
+    user_id = marshmallow.fields.Int(example=3)
156
+    workspace_id = marshmallow.fields.Int(example=4)
91 157
     user = marshmallow.fields.Nested(
92 158
         UserSchema(only=('display_name', 'avatar_url'))
93 159
     )
94 160
 
161
+    class Meta:
162
+        description = 'Workspace Member information'
163
+
95 164
 
96 165
 class ApplicationConfigSchema(marshmallow.Schema):
97 166
     pass
@@ -99,11 +168,23 @@ class ApplicationConfigSchema(marshmallow.Schema):
99 168
 
100 169
 
101 170
 class ApplicationSchema(marshmallow.Schema):
102
-    label = marshmallow.fields.String()
103
-    slug = marshmallow.fields.String()
104
-    fa_icon = marshmallow.fields.String()
105
-    hexcolor = marshmallow.fields.String()
106
-    is_active = marshmallow.fields.Boolean()
171
+    label = marshmallow.fields.String(example='Calendar')
172
+    slug = marshmallow.fields.String(example='calendar')
173
+    fa_icon = marshmallow.fields.String(
174
+        example='file-o',
175
+        description='CSS class of the icon. Example: file-o for using Fontawesome file-o icon',  # nopep8
176
+    )
177
+    hexcolor = marshmallow.fields.String(
178
+        example='#FF0000',
179
+        description='HTML encoded color associated to the application. Example:#FF0000 for red'  # nopep8
180
+    )
181
+    is_active = marshmallow.fields.Boolean(
182
+        example=True,
183
+        description='if true, the application is in use in the context',
184
+    )
107 185
     config = marshmallow.fields.Nested(
108 186
         ApplicationConfigSchema,
109 187
     )
188
+
189
+    class Meta:
190
+        description = 'Tracim Application informations'