Needs better documentation

[DeanWay]

Problem
currently the best way to learn how to use this library is simply to look at examples/item.py but that isn't comprehensive, searchable, or explanatory

Describe the solution you'd like

• mkdocs
• readthedocs
• sphinx
• github markdown

[garry-jeromson]

It'd also be great to include an example of how to declare/use relationships - this is a bit of a black box at the moment.

In any case, a really promising project.

[okeyokoro]

+1 for mkdocs

p.s. thank for making this!

[cickes]

Can someone share a simple example to return a collection of items? Thanks.

[DeanWay]

@cickes

from pydantic import BaseModel
from pydantic_jsonapi import JsonApiRequest, JsonApiResponse


class Item(BaseModel):
    name: str
    quantity: int
    price: float


ITEM_TYPE_NAME = 'item'
ItemRequest = JsonApiRequest(ITEM_TYPE_NAME, Item)
ItemListResponse = JsonApiResponse(ITEM_TYPE_NAME, Item, use_list=True)
# OR
# from pydantic_jsonapi import JsonApiModel
# ItemRequest, ItemListResponse = JsonApiModel(ITEM_TYPE_NAME, Item, list_response=True)


response = ItemListResponse(**{
    'data': [
        {
            "id": "b56ba127bab6459db045d0038a0c06ba",
            "type": "item",
            "attributes": {
                "name": "apple",
                "quantity": 10,
                "price": 1.2
            }
        },
        {
            "id": "abc123def456",
            "type": "item",
            "attributes": {
                'name': 'orange',
                'quantity': 9,
                'price': 2.2
            }
        },
    ]
})
print(response.json(indent=2))

[DeanWay]

note that only the response model allows lists for data since the jsonapi spec does not allow list data for creating, updating, or patching resources: https://jsonapi.org/format/#crud-creating

[cickes]

How would this work using the same approach as the examples/item.py? Assuming that the items are stored in a List of item_rows.

ItemResponse = JsonApiResponse(ITEM_TYPE_NAME, Item)

# Simple post method logic
def item_post_method(item_request: ItemRequest) -> ItemResponse:
    attributes = item_request.data.attributes
    item_row = ItemData(**attributes.dict())
    return ItemResponse(
        data=ItemResponse.resource_object(
            id=item_row.id,
            attributes=item_row
        )
    )

[DeanWay]

@cickes I added something with a list response to the example: #22 check it out

[vbyrd]

Some documentation recommendations:

This seems to work for enhanced clarity and to fall in line with Pydantic BaseModel class. linting doesn't like UpperCaseCamelCase variable names of the existing example.

from pydantic import BaseModel
from pydantic_jsonapi import JsonApiResponse

class Item(BaseModel):
  name: str
  quantity: int
  price: float

class ResponseItem(JsonApiResponse('item', Item)):
  pass

class ResponseItems(JsonApiResponse('item', Item, use_list=True)):
  pass

#Multiple Items
response_items = ResponseItems(**{
    'data': [
        {
            "id": "b56ba127bab6459db045d0038a0c06ba",
            "type": "item",
            "attributes": {
                "name": "apple",
                "quantity": 10,
                "price": 1.2
            }
        },
        {
            "id": "abc123def456",
            "type": "item",
            "attributes": {
                'name': 'orange',
                'quantity': 9,
                'price': 2.2
            }
        },
    ]
})
print(response_items.json(indent=2))

# Single Item
response_item = ResponseItem(**{
    'data': {
        'id': 'abc123def456984',
        'type': 'item',
        'attributes': {
            'name': 'apple',
            'quantity': 10,
            'price': 1.20,
        },
    }
})
print(response_item.json(indent=2))