📝 Add mkdocs

docs/models.md

@@ -0,0 +1,102 @@
+# Models
+
+OhMyAPI uses [Tortoise](https://tortoise.github.io/) - an easy-to-use asyncio ORM (Object Relational Mapper) inspired by Django.
+
+Models are exposed via a Python module named `models` in the app's directory.
+OhMyAPI auto-detects all models exposed this way.
+If the `models` module is a package, OhMyAPI will search through its submodules recursively.
+
+## Writing models
+
+### Your first simple model
+
+```python
+from ohmyapi.db import Model, field
+
+
+class Restaurant(Model):
+    id: int = field.IntField(pk=True)
+    name: str = field.CharField(max_length=255)
+    description: str = field.TextField()
+    location: str = field.CharField(max_length=255)
+```
+
+### ForeignKeyRelations
+
+You can define relationships between models.
+
+```python
+from ohmyapi.db import Model, field
+
+from decimal import Decimal
+
+
+class Restaurant(Model):
+    id: int = field.IntField(pk=True)
+    name: str = field.CharField(max_length=255)
+    description: str = field.TextField()
+    location: str = field.CharField(max_length=255)
+
+
+class Dish(Model):
+    id: int = field.IntField(pk=True)
+    restaurant: field.ForeignKeyRelation[Restaurant] = field.ForeignKeyField(
+        "restaurant.Restaurant",
+        related_name="dishes",
+    )
+    name: str = field.CharField(max_length=255)
+    price: Decimal = field.DecimalField(max_digits=10, decimal_places=2)
+
+
+class Order(Model):
+    id: int = field.IntField(pk=True)
+    restaurant: field.ForeignKeyRelation[Restaurant] = field.ForeignKeyField(
+        'restaurant.Restaurant',
+        related_name="dishes",
+    )
+    dishes: field.ManyToManyRelation[Dish] = field.ManyToManyField(
+        "restaurant.Dish",
+        relatated_name="orders",
+        through="dishesordered",
+    )
+```
+
+## Pydantic Schema Validation
+
+Each model has a builtin `Schema` class that provides easy access to Pydantic models for schema validation.
+Each model provides a default schema and a readonly schema, which you can obtain via the `get` method or by calling Schema() directly.
+The default schema contains the full collection of fields of the Tortoise model.
+The readonly schema excludes the primary-key field, as well as all readonly fields.
+
+```python
+In [1]: from restaurant.models import Restaurant
+
+In [2]: Restaurant.Schema.get()
+Out[2]: tortoise.contrib.pydantic.creator.RestaurantSchema
+
+In [3]: Restaurant.Schema.get(readonly=True)
+Out[3]: tortoise.contrib.pydantic.creator.RestaurantSchemaReadonly
+
+In [4]: data = {
+   ...:     "name": "My Pizzeria",
+   ...:     "description": "Awesome Pizza!",
+   ...:     "location": "Berlin",
+   ...: }
+
+In [5]: Restaurant.Schema.get(readonly=True)(**data)
+Out[5]: RestaurantSchemaReadonly(name='My Pizzeria', description='Awesome Pizza!', location='Berlin')
+
+In [6]: Restaurant(**_.model_dump())
+Out[6]: <Restaurant>
+```
+
+You can customize the fields to be include in the Pydantic schema:
+
+```python
+class MyModel(Model):
+    [...]
+
+    class Schema:
+        include: List[str] = []  # list of fields to include
+        exclude: List[str] = []  # list of fields to exclude
+```