Use schema instance instead of class definitions when documenting API
- 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.