✨ Add include, exclude, and by_alias to path operation methods (#264)

* ✨ Make jsonable_encoder's include and exclude receive sequences

* ✨ Add include, exclude, and by_alias to app and router

* ✨ Add and update tutorial code with new parameters

* 📝 Update docs for new parameters and add docs for updating data

* ✅ Add tests for consistency in path operation methods

* ✅ Add tests for new parameters and update tests

docs/tutorial/body-updates.md

@@ -0,0 +1,97 @@
+## Update replacing with `PUT`
+
+To update an item you can use the [HTTP `PUT`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PUT) operation.
+
+You can use the `jsonable_encoder` to convert the input data to data that can be stored as JSON (e.g. with a NoSQL database). For example, converting `datetime` to `str`.
+
+```Python hl_lines="30 31 32 33 34 35"
+{!./src/body_updates/tutorial001.py!}
+```
+
+`PUT` is used to receive data that should replace the existing data.
+
+### Warning about replacing
+
+That means that if you want to update the item `bar` using `PUT` with a body containing:
+
+```Python
+{
+    "name": "Barz",
+    "price": 3,
+    "description": None,
+}
+```
+
+because it doesn't include the already stored attribute `"tax": 20.2`, the input model would take the default value of `"tax": 10.5`.
+
+And the data would be saved with that "new" `tax` of `10.5`.
+
+## Partial updates with `PATCH`
+
+You can also use the [HTTP `PATCH`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH) operation to *partially* update data.
+
+This means that you can send only the data that you want to update, leaving the rest intact.
+
+!!! Note
+    `PATCH` is less commonly used and known than `PUT`.
+
+    And many teams use only `PUT`, even for partial updates.
+
+    You are **free** to use them however you want, **FastAPI** doesn't impose any restrictions.
+
+    But this guide shows you, more or less, how they are intended to be used.
+
+### Using Pydantic's `skip_defaults` parameter
+
+If you want to receive partial updates, it's very useful to use the parameter `skip_defaults` in Pydantic's model's `.dict()`.
+
+Like `item.dict(skip_defaults=True)`.
+
+That would generate a `dict` with only the data that was set when creating the `item` model, excluding default values.
+
+Then you can use this to generate a `dict` with only the data that was set, omitting default values:
+
+```Python hl_lines="34"
+{!./src/body_updates/tutorial002.py!}
+```
+
+### Using Pydantic's `update` parameter
+
+Now, you can create a copy of the existing model using `.copy()`, and pass the `update` parameter with a `dict` containing the data to update.
+
+Like `stored_item_model.copy(update=update_data)`:
+
+```Python hl_lines="35"
+{!./src/body_updates/tutorial002.py!}
+```
+
+### Partial updates recap
+
+In summary, to apply partial updates you would:
+
+* (Optionally) use `PATCH` instead of `PUT`.
+* Retrieve the stored data.
+* Put that data in a Pydantic model.
+* Generate a `dict` without default values from the input model (using `skip_defaults`).
+    * This way you can update only the values actually set by the user, instead of overriding values already stored with default values in your model.
+* Create a copy of the stored model, updating it's attributes with the received partial updates (using the `update` parameter).
+* Convert the copied model to something that can be stored in your DB (for example, using the `jsonable_encoder`).
+    * This is comparable to using the model's `.dict()` method again, but it makes sure (and converts) the values to data types that can be converted to JSON, for example, `datetime` to `str`.
+* Save the data to your DB.
+* Return the updated model.
+
+```Python hl_lines="30 31 32 33 34 35 36 37"
+{!./src/body_updates/tutorial002.py!}
+```
+
+!!! tip
+    You can actually use this same technique with an HTTP `PUT` operation.
+
+    But the example here uses `PATCH` because it was created for these use cases.
+
+!!! note
+    Notice that the input model is still validated.
+
+    So, if you want to receive partial updates that can omit all the attributes, you need to have a model with all the attributes marked as optional (with default values or `None`).
+
+    To distinguish from the models with all optional values for **updates** and models with required values for **creation**, you can use the ideas described in <a href="https://fastapi.tiangolo.com/tutorial/extra-models/" target="_blank">Extra Models</a>.

docs/tutorial/response-model.md

@@ -13,12 +13,14 @@ You can declare the model used for the response with the parameter `response_mod
 !!! note
     Notice that `response_model` is a parameter of the "decorator" method (`get`, `post`, etc). Not of your path operation function, like all the parameters and body.
 
-It receives a standard Pydantic model and will:
+It receives the same type you would declare for a Pydantic model attribute, so, it can be a Pydantic model, but it can also be, e.g. a `list` of Pydantic models, like `List[Item]`.
 
-* Convert the output data to the type declarations of the model
-* Validate the data
-* Add a JSON Schema for the response, in the OpenAPI path operation
-* Will be used by the automatic documentation systems
+FastAPI will use this `response_model` to:
+
+* Convert the output data to its type declaration.
+* Validate the data.
+* Add a JSON Schema for the response, in the OpenAPI path operation.
+* Will be used by the automatic documentation systems.
 
 But most importantly:
 
@@ -45,7 +47,7 @@ Now, whenever a browser is creating a user with a password, the API will return
 
 In this case, it might not be a problem, because the user himself is sending the password.
 
-But if we use the same model for another path operation, we could be sending the passwords of our users to every client.
+But if we use the same model for another path operation, we could be sending our user's passwords to every client.
 
 !!! danger
     Never send the plain password of a user in a response.
@@ -84,7 +86,7 @@ And both models will be used for the interactive API documentation:
 
 ## Response Model encoding parameters
 
-If your response model has default values, like:
+Your response model could have default values, like:
 
 ```Python hl_lines="11 13 14"
 {!./src/response_model/tutorial004.py!}
@@ -94,6 +96,12 @@ If your response model has default values, like:
 * `tax: float = None` has a default of `None`.
 * `tags: List[str] = []` has a default of an empty list: `[]`.
 
+but you might want to omit them from the result if they were not actually stored.
+
+For example, if you have models with many optional attributes in a NoSQL database, but you don't want to send very long JSON responses full of default values.
+
+### Use the `response_model_skip_defaults` parameter
+
 You can set the *path operation decorator* parameter `response_model_skip_defaults=True`:
 
 ```Python hl_lines="24"
@@ -114,7 +122,7 @@ So, if you send a request to that *path operation* for the item with ID `foo`, t
 !!! info
     FastAPI uses Pydantic model's `.dict()` with <a href="https://pydantic-docs.helpmanual.io/#copying" target="_blank">its `skip_defaults` parameter</a> to achieve this.
 
-### Data with values for fields with defaults
+#### Data with values for fields with defaults
 
 But if your data has values for the model's fields with default values, like the item with ID `bar`:
 
@@ -129,7 +137,7 @@ But if your data has values for the model's fields with default values, like the
 
 they will be included in the response.
 
-### Data with the same values as the defaults
+#### Data with the same values as the defaults
 
 If the data has the same values as the default ones, like the item with ID `baz`:
 
@@ -152,34 +160,35 @@ So, they will be included in the JSON response.
 
     They can be a list (`[]`), a `float` of `10.5`, etc.
 
-### Use cases
+### `response_model_include` and `response_model_exclude`
 
-This is very useful in several scenarios.
+You can also use the *path operation decorator* parameters `response_model_include` and `response_model_exclude`.
 
-For example if you have models with many optional attributes in a NoSQL database, but you don't want to send very long JSON responses full of default values.
+They take a `set` of `str` with the name of the attributes to include (omitting the rest) or to exclude (including the rest).
 
-### Using Pydantic's `skip_defaults` directly
+This can be used as a quick shortcut if you have only one Pydantic model and want to remove some data from the output.
 
-You can also use your model's `.dict(skip_defaults=True)` in your code.
+!!! tip
+    But it is still recommended to use the ideas above, using multiple classes, instead of these parameters.
 
-For example, you could receive a model object as a body payload, and update your stored data using only the attributes set, not the default ones:
+    This is because the JSON Schema generated in your app's OpenAPI (and the docs) will still be the one for the complete model, even if you use `response_model_include` or `response_model_exclude` to omit some attributes.
 
-```Python hl_lines="31 32 33 34 35"
-{!./src/response_model/tutorial004.py!}
+```Python hl_lines="29 35"
+{!./src/response_model/tutorial005.py!}
 ```
 
 !!! tip
-    It's common to use the HTTP `PUT` operation to update data.
+    The syntax `{"name", "description"}` creates a `set` with those two values.
 
-    In theory, `PUT` should be used to "replace" the entire contents.
+    It is equivalent to `set(["name", "description"])`.
 
-    The less known HTTP `PATCH` operation is also used to update data.
+#### Using `list`s instead of `set`s
 
-    But `PATCH` is expected to be used when *partially* updating data. Instead of *replacing* the entire content.
+If you forget to use a `set` and use a `list` or `tuple` instead, FastAPI will still convert it to a `set` and it will work correctly:
 
-    Still, this is just a small detail, and many teams and code bases use `PUT` instead of `PATCH` for all updates, including to *partially* update contents.
-
-    You can use `PUT` or `PATCH` however you wish.
+```Python hl_lines="29 35"
+{!./src/response_model/tutorial006.py!}
+```
 
 ## Recap