update migration

CHANGES.md

@@ -18,6 +18,7 @@
 
 ### Changed
 
+* Replaced `@attrs` with python `@dataclass` for `APIRequest` (model for GET request) class type [#714](https://github.com/stac-utils/stac-fastapi/pull/714)
 * Moved `GETPagination`, `POSTPagination`, `GETTokenPagination` and `POSTTokenPagination` to `stac_fastapi.extensions.core.pagination.request` submodule [#717](https://github.com/stac-utils/stac-fastapi/pull/717)
 
 ## [3.0.0a4] - 2024-06-27

docs/src/migrations/v3.0.0.md

@@ -13,7 +13,6 @@ Most of the **stac-fastapi's** dependencies have been upgraded. Moving from pyda
 
 In addition to pydantic v2 update, `stac-pydantic` has been updated to better match the STAC and STAC-API specifications (see https://github.com/stac-utils/stac-pydantic/blob/main/CHANGELOG.md#310-2024-05-21)
 
-
 ## Deprecation
 
 * the `ContextExtension` have been removed (see https://github.com/stac-utils/stac-pydantic/pull/138) and was replaced by optional `NumberMatched` and `NumberReturned` attributes, defined by the OGC features specification.
@@ -24,6 +23,49 @@ In addition to pydantic v2 update, `stac-pydantic` has been updated to better ma
 
 * `PostFieldsExtension.filter_fields` property has been removed.
 
+## `attr` -> `dataclass` for APIRequest models
+
+Models for **GET** requests, defining the path and query parameters, now uses python `dataclass` instead of `attr`.
+
+```python
+# before
+@attr.s
+class CollectionModel(APIRequest):
+    collections: Optional[str] = attr.ib(default=None, converter=str2list)
+
+# now
+@dataclass
+class CollectionModel(APIRequest):
+    collections: Annotated[Optional[str], Query()] = None
+
+    def __post_init__(self):
+        """convert attributes."""
+        if self.collections:
+            self.collections = str2list(self.collections)  # type: ignore
+
+```
+
+!!! warning
+
+    if you want to extend a class with a `required` attribute (without default), you will have to write all the attributes to avoid having *non-default* attributes defined after *default* attributes (ref: https://github.com/stac-utils/stac-fastapi/pull/714/files#r1651557338)
+
+    ```python
+    @dataclass
+    class A:
+        value: Annotated[str, Query()]
+
+    # THIS WON'T WORK
+    @dataclass
+    class B(A):
+        another_value: Annotated[str, Query(...)]
+
+    # DO THIS
+    @dataclass
+    class B(A):
+        another_value: Annotated[str, Query(...)]
+        value: Annotated[str, Query()]
+    ```
+
 ## Middlewares configuration
 
 The `StacApi.middlewares` attribute has been updated to accept a list of `starlette.middleware.Middleware`. This enables dynamic configuration of middlewares (see https://github.com/stac-utils/stac-fastapi/pull/442).