From ef55753ea932989ae8e505779f55a694b7ff9c40 Mon Sep 17 00:00:00 2001 From: Suren Khorenyan Date: Fri, 15 Dec 2023 17:36:51 +0300 Subject: [PATCH] update docs --- README.md | 18 +++++++------- docs/api_limited_methods_example.rst | 15 ++++++++++-- docs/filtering.rst | 24 +++++++++---------- .../client_generated_id/schematic_example.py | 2 +- docs/quickstart.rst | 16 ++++++------- examples/api_for_tortoise_orm/urls.py | 2 +- examples/api_limited_methods.py | 2 +- examples/api_minimal.py | 2 +- 8 files changed, 46 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 7494725c..ecc53d43 100644 --- a/README.md +++ b/README.md @@ -148,7 +148,7 @@ def add_routes(app: FastAPI): router: APIRouter = APIRouter() RoutersJSONAPI( router=router, - path="/user", + path="/users", tags=["User"], class_detail=UserDetailView, class_list=UserListView, @@ -195,11 +195,11 @@ if __name__ == "__main__": This example provides the following API structure: -| URL | method | endpoint | Usage | -|------------------|--------|-------------|---------------------------| -| `/user` | GET | user_list | Get a collection of users | -| `/user` | POST | user_list | Create a user | -| `/user` | DELETE | user_list | Delete users | -| `/user/{obj_id}` | GET | user_detail | Get user details | -| `/user/{obj_id}` | PATCH | user_detail | Update a user | -| `/user/{obj_id}` | DELETE | user_detail | Delete a user | +| URL | method | endpoint | Usage | +|-------------------|--------|-------------|---------------------------| +| `/users` | GET | user_list | Get a collection of users | +| `/users` | POST | user_list | Create a user | +| `/users` | DELETE | user_list | Delete users | +| `/users/{obj_id}` | GET | user_detail | Get user details | +| `/users/{obj_id}` | PATCH | user_detail | Update a user | +| `/users/{obj_id}` | DELETE | user_detail | Delete a user | diff --git a/docs/api_limited_methods_example.rst b/docs/api_limited_methods_example.rst index e0adb602..561b58d9 100644 --- a/docs/api_limited_methods_example.rst +++ b/docs/api_limited_methods_example.rst @@ -14,7 +14,7 @@ Set ``methods`` on Routers registration: RoutersJSONAPI( router=router, - path="/user", + path="/users", tags=["User"], class_detail=UserDetailView, class_list=UserListView, @@ -29,7 +29,18 @@ Set ``methods`` on Routers registration: ) -Full code example: +This will limit generated views to: + +======================== ====== ============= =========================== +URL method endpoint Usage +======================== ====== ============= =========================== +/users GET user_list Get a collection of users +/users POST user_list Create a user +/users/{user_id} GET user_detail Get user details +======================== ====== ============= =========================== + + +Full code example (should run "as is"): .. literalinclude:: ../examples/api_limited_methods.py :language: python diff --git a/docs/filtering.rst b/docs/filtering.rst index 000d63dd..1b8493ca 100644 --- a/docs/filtering.rst +++ b/docs/filtering.rst @@ -24,7 +24,7 @@ So this is a first example: .. sourcecode:: http - GET /user?filter=[{"name":"first_name","op":"eq","val":"John"}] HTTP/1.1 + GET /users?filter=[{"name":"first_name","op":"eq","val":"John"}] HTTP/1.1 Accept: application/vnd.api+json In this example we want to retrieve user records for people named John. So we can see that the filtering interface completely fits that of SQLAlchemy: a list a filter information. @@ -37,7 +37,7 @@ Example with field: .. sourcecode:: http - GET /user?filter=[{"name":"first_name","op":"eq","field":"birth_date"}] HTTP/1.1 + GET /users?filter=[{"name":"first_name","op":"eq","field":"birth_date"}] HTTP/1.1 Accept: application/vnd.api+json In this example, we want to retrieve people whose name is equal to their birth_date. This example is absurd, it's just here to explain the syntax of this kind of filter. @@ -74,7 +74,7 @@ There is a shortcut to achieve the same filtering: .. sourcecode:: http - GET /user?filter=[{"name":"group.name","op":"ilike","val":"%admin%"}] HTTP/1.1 + GET /users?filter=[{"name":"group.name","op":"ilike","val":"%admin%"}] HTTP/1.1 Accept: application/vnd.api+json You can also use boolean combination of operations: @@ -116,7 +116,7 @@ You can also use boolean combination of operations: .. sourcecode:: http - GET /user?filter=[{"name":"group.name","op":"ilike","val":"%admin%"},{"or":[{"not":{"name":"first_name","op":"eq","val":"John"}},{"and":[{"name":"first_name","op":"like","val":"%Jim%"},{"name":"date_create","op":"gt","val":"1990-01-01"}]}]}] HTTP/1.1 + GET /users?filter=[{"name":"group.name","op":"ilike","val":"%admin%"},{"or":[{"not":{"name":"first_name","op":"eq","val":"John"}},{"and":[{"name":"first_name","op":"like","val":"%Jim%"},{"name":"date_create","op":"gt","val":"1990-01-01"}]}]}] HTTP/1.1 Accept: application/vnd.api+json @@ -124,14 +124,14 @@ Filtering records by a field that is null .. sourcecode:: http - GET /user?filter=[{"name":"name","op":"is_","val":null}] HTTP/1.1 + GET /users?filter=[{"name":"name","op":"is_","val":null}] HTTP/1.1 Accept: application/vnd.api+json Filtering records by a field that is not null .. sourcecode:: http - GET /user?filter=[{"name":"name","op":"isnot","val":null}] HTTP/1.1 + GET /users?filter=[{"name":"name","op":"isnot","val":null}] HTTP/1.1 Accept: application/vnd.api+json @@ -172,14 +172,14 @@ For example .. sourcecode:: http - GET /user?filter[first_name]=John HTTP/1.1 + GET /users?filter[first_name]=John HTTP/1.1 Accept: application/vnd.api+json equals: .. sourcecode:: http - GET /user?filter=[{"name":"first_name","op":"eq","val":"John"}] HTTP/1.1 + GET /users?filter=[{"name":"first_name","op":"eq","val":"John"}] HTTP/1.1 Accept: application/vnd.api+json @@ -187,7 +187,7 @@ You can also use more than one simple filter in a request: .. sourcecode:: http - GET /user?filter[first_name]=John&filter[gender]=male HTTP/1.1 + GET /users?filter[first_name]=John&filter[gender]=male HTTP/1.1 Accept: application/vnd.api+json which is equal to: @@ -209,17 +209,17 @@ which is equal to: .. sourcecode:: http - GET /user?filter=[{"name":"first_name","op":"eq","val":"John"},{"name":"gender","op":"eq","val":"male"}] HTTP/1.1 + GET /users?filter=[{"name":"first_name","op":"eq","val":"John"},{"name":"gender","op":"eq","val":"male"}] HTTP/1.1 You can also use relationship attribute in a request: .. sourcecode:: http - GET /user?filter[group_id]=1 HTTP/1.1 + GET /users?filter[group_id]=1 HTTP/1.1 Accept: application/vnd.api+json which is equal to: .. sourcecode:: http - GET /user?filter=[{"name":"group.id","op":"eq","val":"1"}] HTTP/1.1 + GET /users?filter=[{"name":"group.id","op":"eq","val":"1"}] HTTP/1.1 diff --git a/docs/python_snippets/client_generated_id/schematic_example.py b/docs/python_snippets/client_generated_id/schematic_example.py index c8f8b26d..ed632748 100644 --- a/docs/python_snippets/client_generated_id/schematic_example.py +++ b/docs/python_snippets/client_generated_id/schematic_example.py @@ -110,7 +110,7 @@ def add_routes(app: FastAPI): router: APIRouter = APIRouter() RoutersJSONAPI( router=router, - path="/user", + path="/users", tags=["User"], class_detail=UserDetailView, class_list=UserListView, diff --git a/docs/quickstart.rst b/docs/quickstart.rst index e667b132..7d87e884 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -27,15 +27,15 @@ This example provides the following API: +----------------+--------+----------------+---------------------------------+ | url | method | endpoint | action | +================+========+================+=================================+ -| /user | GET | user_list | Retrieve a collection of users | +| /users | GET | user_list | Retrieve a collection of users | +----------------+--------+----------------+---------------------------------+ -| /user | POST | user_list | Create a user | +| /users | POST | user_list | Create a user | +----------------+--------+----------------+---------------------------------+ -| /user/ | GET | user_detail | Retrieve details of a user | +| /users/ | GET | user_detail | Retrieve details of a user | +----------------+--------+----------------+---------------------------------+ -| /user/ | PATCH | user_detail | Update a user | +| /users/ | PATCH | user_detail | Update a user | +----------------+--------+----------------+---------------------------------+ -| /user/ | DELETE | user_detail | Delete a user | +| /users/ | DELETE | user_detail | Delete a user | +----------------+--------+----------------+---------------------------------+ in developing @@ -43,11 +43,11 @@ in developing +-------------------------------------------+--------+------------------+------------------------------------------------------+ | url | method | endpoint | action | +===========================================+========+==================+======================================================+ -| /user//group | GET | computer_list | Retrieve a collection computers related to a user | +| /users//group | GET | computer_list | Retrieve a collection computers related to a user | +-------------------------------------------+--------+------------------+------------------------------------------------------+ -| /user//group | POST | computer_list | Create a computer related to a user | +| /users//group | POST | computer_list | Create a computer related to a user | +-------------------------------------------+--------+------------------+------------------------------------------------------+ -| /user//relationships/group | GET | user_computers | Retrieve relationships between a user and computers | +| /users//relationships/group | GET | user_computers | Retrieve relationships between a user and computers | +-------------------------------------------+--------+------------------+------------------------------------------------------+ | /users//relationships/computers | POST | user_computers | Create relationships between a user and computers | +-------------------------------------------+--------+------------------+------------------------------------------------------+ diff --git a/examples/api_for_tortoise_orm/urls.py b/examples/api_for_tortoise_orm/urls.py index 9037b44a..f35f8bd1 100644 --- a/examples/api_for_tortoise_orm/urls.py +++ b/examples/api_for_tortoise_orm/urls.py @@ -36,7 +36,7 @@ def add_routes(app: FastAPI) -> List[Dict[str, Any]]: # TODO: fix example RoutersJSONAPI( router=routers, - path="/user", + path="/users", tags=["User"], class_detail=UserDetail, class_list=UserList, diff --git a/examples/api_limited_methods.py b/examples/api_limited_methods.py index dff77d9c..b2a88a06 100644 --- a/examples/api_limited_methods.py +++ b/examples/api_limited_methods.py @@ -110,7 +110,7 @@ def add_routes(app: FastAPI): router: APIRouter = APIRouter() RoutersJSONAPI( router=router, - path="/user", + path="/users", tags=["User"], class_detail=UserDetailView, class_list=UserListView, diff --git a/examples/api_minimal.py b/examples/api_minimal.py index c3042af9..51d20528 100644 --- a/examples/api_minimal.py +++ b/examples/api_minimal.py @@ -110,7 +110,7 @@ def add_routes(app: FastAPI): router: APIRouter = APIRouter() RoutersJSONAPI( router=router, - path="/user", + path="/users", tags=["User"], class_detail=UserDetailView, class_list=UserListView,