flasgger / flasgger/flasgger

Use schema instance instead of class definitions when documenting API

Open
#256 6 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3.7k
Forks
525
PR merge metrics
No merged PRs in 30d

Description

Hi,
one question regarding using schema instances (objects) instead of class definitions when documenting API. Lets say we have a simple situation:
```python
from marshmallow import Schema, fields

class UserSchema(Schema):
id = fields.Integer(required=True)
name = fields.String()
email = fields.String()

create_schema = UserSchema(exclude=['id'])
read_schema = UserSchema(exclude=[])
update_schema = UserSchema(exclude=['name'])
delete_schema = UserSchema(exclude=[])

user1 = {
'id': 1,
'name': 'user1',
'email': 'user1@gmail.com',
}

print create_schema.dump(user1)
print read_schema.dump(user1)
print update_schema.dump(user1)
print delete_schema.dump(user1)
```

Output looks like:
```bash
MarshalResult(data={u'name': u'user1', u'email': u'user1@gmail.com'}, errors={})
MarshalResult(data={u'email': u'user1@gmail.com', u'name': u'user1', u'id': 1}, errors={})
MarshalResult(data={u'id': 1, u'email': u'user1@gmail.com'}, errors={})
MarshalResult(data={u'email': u'user1@gmail.com', u'name': u'user1', u'id': 1}, errors={})
```

So we have one schema (User) and 4 instances of it; say for CRUD methods. So when we want to do read user(s), all fields are expected to be displayed (exclude list is empty). Similar is for delete. However, when for example we want to create a user object, we should **not** see nor pass the _id_ field. Now if we use UserSchema to describe POST endpoint, we would see all fields from it, but in reality we should **not** see the _id_ field. This can be solved by using separate schema classes, for each CRUD method.

So the question is as follows: shall we use separate schema class definition, depending on CRUD method in question or we maybe use something like **LazyString** to use concrete instance which will be used by the CRUD method itself to serialize/dump data? For more complex, especially nested class, we might have way too many classes to define. On the other hand, I am not sure if using instance serializer(s) instead of schemes is the way to go. Any thoughts?

Also, a side question: are anyOf and oneOf supported?

Thanks in advance

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.