Merge pull request #82 from tracim/fix/better_api_doc

tracim/tests/functional/test_session.py

         assert res.json_body['created']
         assert res.json_body['is_active']
         assert res.json_body['profile']
-        assert isinstance(res.json_body['profile']['id'], int)
         assert res.json_body['profile']['slug'] == 'administrators'
         assert res.json_body['caldav_url'] is None
         assert res.json_body['avatar_url'] is None
         assert res.json_body['created']
         assert res.json_body['is_active']
         assert res.json_body['profile']
-        assert isinstance(res.json_body['profile']['id'], int)
         assert res.json_body['profile']['slug'] == 'administrators'
         assert res.json_body['caldav_url'] is None
         assert res.json_body['avatar_url'] is None

tracim/tests/functional/test_workspaces.py

         assert len(res) == 2
         user_role = res[0]
         assert user_role['role_slug'] == 'workspace-manager'
-        assert user_role['role_id'] == 8
         assert user_role['user_id'] == 1
         assert user_role['workspace_id'] == 1
         assert user_role['user']['display_name'] == 'Global manager'

tracim/views/core_api/schemas.py

 
 
 class ProfileSchema(marshmallow.Schema):
-    id = marshmallow.fields.Int(dump_only=True, validate=OneOf(Profile._IDS))
-    slug = marshmallow.fields.String(attribute='name', validate=OneOf(Profile._NAME))
+    slug = marshmallow.fields.String(
+        attribute='name',
+        validate=OneOf(Profile._NAME),
+        example='managers',
+    )
+
+    class Meta:
+        description = 'User Profile, give user right on whole Tracim instance.'
 
 
 class UserSchema(marshmallow.Schema):
 
-    user_id = marshmallow.fields.Int(dump_only=True)
-    email = marshmallow.fields.Email(required=True)
-    display_name = marshmallow.fields.String()
-    created = marshmallow.fields.DateTime(format='iso8601')
-    is_active = marshmallow.fields.Bool()
+    user_id = marshmallow.fields.Int(dump_only=True, example=3)
+    email = marshmallow.fields.Email(
+        required=True,
+        example='suri.cate@algoo.fr'
+    )
+    display_name = marshmallow.fields.String(
+        example='Suri Cate',
+    )
+    created = marshmallow.fields.DateTime(
+        format='iso8601',
+        description='User account creation date (iso8601 format).',
+    )
+    is_active = marshmallow.fields.Bool(
+        example=True,
+         # TODO - G.M - Explains this value.
+    )
     # TODO - G.M - 17-04-2018 - Restrict timezone values
-    timezone = marshmallow.fields.String()
+    timezone = marshmallow.fields.String(
+        example="Paris/Europe",
+    )
     # TODO - G.M - 17-04-2018 - check this, relative url allowed ?
     caldav_url = marshmallow.fields.Url(
         allow_none=True,
         relative=True,
-        attribute='calendar_url'
+        attribute='calendar_url',
+        example="/api/v2/calendar/user/3.ics/",
+        description="The url for calendar CalDAV direct access",
+    )
+    avatar_url = marshmallow.fields.Url(
+        allow_none=True,
+        example="/api/v2/assets/avatars/suri-cate.jpg",
+        description="avatar_url is the url to the image file. "
+                    "If no avatar, then set it to null "
+                    "(and frontend will interpret this with a default avatar)",
     )
-    avatar_url = marshmallow.fields.Url(allow_none=True)
     profile = marshmallow.fields.Nested(
         ProfileSchema,
         many=False,
     )
 
+    class Meta:
+        description = 'User account of Tracim'
+
 
 class UserIdPathSchema(marshmallow.Schema):
-    user_id = marshmallow.fields.Int()
+    user_id = marshmallow.fields.Int(example=3)
 
 
 class WorkspaceIdPathSchema(marshmallow.Schema):
-    workspace_id = marshmallow.fields.Int()
+    workspace_id = marshmallow.fields.Int(example=4)
 
 
 class BasicAuthSchema(marshmallow.Schema):
 
-    email = marshmallow.fields.Email(required=True)
-    password = marshmallow.fields.String(required=True, load_only=True)
+    email = marshmallow.fields.Email(
+        example='suri.cate@algoo.fr',
+        required=True
+    )
+    password = marshmallow.fields.String(
+        example='8QLa$<w',
+        required=True,
+        load_only=True,
+    )
+
+    class Meta:
+        description = 'Entry for HTTP Basic Auth'
 
     @post_load
     def make_login(self, data):
 
 
 class NoContentSchema(marshmallow.Schema):
+
+    class Meta:
+        description = 'Empty Schema'
     pass
 
 
 class WorkspaceMenuEntrySchema(marshmallow.Schema):
-    slug = marshmallow.fields.String()
-    label = marshmallow.fields.String()
-    route = marshmallow.fields.String()
-    hexcolor = marshmallow.fields.String()
-    fa_icon = marshmallow.fields.String()
+    slug = marshmallow.fields.String(example='markdown-pages')
+    label = marshmallow.fields.String(example='Markdown Documents')
+    route = marshmallow.fields.String(
+        example='/#/workspace/{workspace_id}/contents/?type=mardown-page',
+        description='the route is the frontend route. '
+                    'It may include workspace_id '
+                    'which must be replaced on backend size '
+                    '(the route must be ready-to-use)'
+    )
+    fa_icon = marshmallow.fields.String(
+        example='file-text-o',
+        description='CSS class of the icon. Example: file-o for using Fontawesome file-text-o icon',  # nopep8
+    )
+    hexcolor = marshmallow.fields.String(
+        example='#F0F9DC',
+        description='Hexadecimal color of the entry.'
+    )
+
+    class Meta:
+        description = 'Entry element of a workspace menu'
 
 
 class WorkspaceDigestSchema(marshmallow.Schema):
-    id = marshmallow.fields.Int()
-    label = marshmallow.fields.String()
+    id = marshmallow.fields.Int(example=4)
+    label = marshmallow.fields.String(example='Intranet')
     sidebar_entries = marshmallow.fields.Nested(
         WorkspaceMenuEntrySchema,
         many=True,
     )
 
+    class Meta:
+        description = 'Digest of workspace informations'
+
 
 class WorkspaceSchema(WorkspaceDigestSchema):
-    slug = marshmallow.fields.String()
-    description = marshmallow.fields.String()
+    slug = marshmallow.fields.String(example='intranet')
+    description = marshmallow.fields.String(example='All intranet data.')
+
+    class Meta:
+        description = 'Full workspace informations'
 
 
 class WorkspaceMemberSchema(marshmallow.Schema):
-    role_id = marshmallow.fields.Int(validate=OneOf(UserRoleInWorkspace.get_all_role_values()))  # nopep8
-    role_slug = marshmallow.fields.String(validate=OneOf(UserRoleInWorkspace.get_all_role_slug()))  # nopep8
-    user_id = marshmallow.fields.Int()
-    workspace_id = marshmallow.fields.Int()
+    role_slug = marshmallow.fields.String(
+        example='contributor',
+        validate=OneOf(UserRoleInWorkspace.get_all_role_slug())
+    )
+    user_id = marshmallow.fields.Int(example=3)
+    workspace_id = marshmallow.fields.Int(example=4)
     user = marshmallow.fields.Nested(
         UserSchema(only=('display_name', 'avatar_url'))
     )
 
+    class Meta:
+        description = 'Workspace Member information'
+
 
 class ApplicationConfigSchema(marshmallow.Schema):
     pass
 
 
 class ApplicationSchema(marshmallow.Schema):
-    label = marshmallow.fields.String()
-    slug = marshmallow.fields.String()
-    fa_icon = marshmallow.fields.String()
-    hexcolor = marshmallow.fields.String()
-    is_active = marshmallow.fields.Boolean()
+    label = marshmallow.fields.String(example='Calendar')
+    slug = marshmallow.fields.String(example='calendar')
+    fa_icon = marshmallow.fields.String(
+        example='file-o',
+        description='CSS class of the icon. Example: file-o for using Fontawesome file-o icon',  # nopep8
+    )
+    hexcolor = marshmallow.fields.String(
+        example='#FF0000',
+        description='HTML encoded color associated to the application. Example:#FF0000 for red'  # nopep8
+    )
+    is_active = marshmallow.fields.Boolean(
+        example=True,
+        description='if true, the application is in use in the context',
+    )
     config = marshmallow.fields.Nested(
         ApplicationConfigSchema,
     )
+
+    class Meta:
+        description = 'Tracim Application informations'