Files
Django_TasksApp/main/food/api_schema.py
T
2026-10-09 14:43:46 +02:00

91 lines
4.9 KiB
Python

"""Small public OpenAPI document; no interactive production documentation UI."""
from django.http import JsonResponse
from django.views.decorators.http import require_GET
def operation(summary, scope, request=None, response=None, multipart=False):
result = {
'summary': summary,
'security': [{'bearerToken': []}],
'x-required-scope': scope,
'responses': {
'200': {'description': 'Success', 'content': {'application/json': {'schema': response or {'type': 'object'}}}},
'400': {'description': 'Invalid request'}, '401': {'description': 'Invalid, revoked, or expired token'},
'403': {'description': 'Missing scope'}, '404': {'description': 'Not found'},
},
}
if request:
result['requestBody'] = {'required': True, 'content': {
'multipart/form-data' if multipart else 'application/json': {'schema': request}}}
return result
ENTRY = {'type': 'object', 'properties': {
'meal': {'type': 'string', 'enum': ['breakfast', 'lunch', 'dinner', 'snacks']},
'product_id': {'type': 'string', 'format': 'uuid'},
'product_name': {'type': 'string'}, 'brand': {'type': 'string'}, 'barcode': {'type': 'string'},
'amount': {'type': 'string', 'description': 'Positive decimal'},
'unit': {'type': 'string', 'enum': ['g', 'ml']},
'date': {'type': 'string', 'format': 'date', 'description': 'Defaults to the user local date'},
'time': {'type': 'string', 'format': 'time'},
'portion_label': {'type': 'string'},
**{field: {'type': ['string', 'null'], 'description': 'Decimal nutrition amount'} for field in
('calories_kcal', 'carbohydrates_g', 'protein_g', 'fat_g', 'fibre_g', 'sugars_g', 'salt_g')},
}}
INVENTORY = {'type': 'object', 'properties': {
'product_id': {'type': 'string', 'format': 'uuid'}, 'quantity': {'type': 'integer', 'minimum': 1},
'location': {'type': 'string'}, 'category': {'type': 'string'}, 'notes': {'type': 'string'},
'opened': {'type': 'boolean'}, 'best_before': {'type': ['string', 'null'], 'format': 'date'},
}}
UPLOAD = {'type': 'object', 'required': ['image'], 'properties': {
'image': {'type': 'string', 'format': 'binary'}, 'caption': {'type': 'string'},
}}
@require_GET
def schema(request):
document = {
'openapi': '3.1.0', 'info': {'title': 'TaskNest Food and Kitchen API', 'version': '1.0.0'},
'servers': [{'url': '/api/v1'}],
'components': {'securitySchemes': {'bearerToken': {'type': 'http', 'scheme': 'bearer'}}},
'paths': {
'/food/today/': {'get': operation('Food log for an optional local calendar date, defaulting to today', 'food:read')},
'/food/products/': {'get': operation('Search own food products', 'food:read')},
'/food/log/': {'post': operation('Create food log entry', 'food:write', ENTRY)},
'/food/log/{id}/': {
'get': operation('Read own entry', 'food:read'),
'patch': operation('Update own entry', 'food:write', ENTRY),
'delete': operation('Delete own entry', 'food:write'),
},
'/food/log/{id}/attachments/': {'post': operation('Upload image for own entry', 'food:write', UPLOAD, multipart=True)},
'/food/attachments/{id}/file/': {'get': operation('Download own attachment', 'food:read')},
'/food/attachments/{id}/': {'delete': operation('Delete own attachment', 'food:write')},
'/kitchen/items/': {
'get': operation('Search own inventory', 'inventory:read'),
'post': operation('Create inventory item', 'inventory:write', INVENTORY),
},
'/kitchen/items/{id}/': {
'get': operation('Read own inventory item', 'inventory:read'),
'patch': operation('Update own inventory item', 'inventory:write', INVENTORY),
'delete': operation('Delete own inventory item', 'inventory:write'),
},
},
}
for path, methods in document['paths'].items():
if '{id}' in path:
methods['parameters'] = [{'name': 'id', 'in': 'path', 'required': True,
'schema': {'type': 'string', 'format': 'uuid'}}]
if 'post' in methods:
methods['post']['responses']['201'] = methods['post']['responses'].pop('200')
document['paths']['/food/today/']['get']['parameters'] = [{
'name': 'date', 'in': 'query', 'required': False,
'description': 'Local calendar date; defaults to today in the user time zone.',
'schema': {'type': 'string', 'format': 'date'},
}]
document['paths']['/food/attachments/{id}/file/']['get']['responses']['200'] = {
'description': 'Owned image bytes',
'content': {mime: {'schema': {'type': 'string', 'format': 'binary'}}
for mime in ('image/jpeg', 'image/png', 'image/webp')},
}
return JsonResponse(document)