125 lines
7.7 KiB
Python
125 lines
7.7 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'},
|
|
'remaining_amount': {'type': ['string', 'null'], 'description': 'Only for one opened package with known size'},
|
|
}}
|
|
PRODUCT = {'type': 'object', 'required': ['name'], 'properties': {
|
|
'name': {'type': 'string', 'maxLength': 255}, 'brand': {'type': 'string', 'maxLength': 255},
|
|
'barcode': {'type': ['string', 'null']}, 'package_quantity': {'type': ['string', 'number', 'null']},
|
|
'package_unit': {'type': ['string', 'null'], 'enum': ['g', 'ml', None]},
|
|
'nutrition_per_100': {'type': ['object', 'null']}, 'source': {'type': 'string', 'enum': ['manual']},
|
|
}}
|
|
GROCERIES = {'type': 'object', 'required': ['items'], 'properties': {
|
|
'items': {'type': 'array', 'minItems': 1, 'maxItems': 20, 'items': {'type': 'object'}},
|
|
'create_missing_products': {'type': 'boolean'},
|
|
}}
|
|
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/products/lookup/': {'get': operation('Look up local and optional Open Food Facts product candidates', 'food:read')},
|
|
'/food/products/create/': {'post': operation('Create or reuse an owned manual food product', 'food:write', PRODUCT)},
|
|
'/food/products/import/': {'post': operation('Import a selected Open Food Facts barcode', 'food:write',
|
|
{'type': 'object', 'required': ['barcode'], 'properties': {'barcode': {'type': 'string'}}})},
|
|
'/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/import-groceries/': {'post': operation('Import up to 20 groceries with per-item results',
|
|
'inventory:write + food:write', GROCERIES)},
|
|
'/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'),
|
|
},
|
|
'/kitchen/stock/': {'get': operation('Read product stock and packages', 'inventory:read')},
|
|
'/kitchen/consumption/preview/': {'post': operation('Preview package deductions without changing stock', 'inventory:read')},
|
|
'/kitchen/consumption/': {'post': operation('Consume stock atomically with Idempotency-Key', 'inventory:write')},
|
|
'/kitchen/consumption/{id}/undo/': {'post': operation('Undo a safe consumption transaction', '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')
|
|
for path in ('/kitchen/consumption/preview/', '/kitchen/consumption/',
|
|
'/kitchen/consumption/{id}/undo/'):
|
|
document['paths'][path]['post']['responses']['200'] = document['paths'][path]['post']['responses'].pop('201')
|
|
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/products/lookup/']['get']['parameters'] = [
|
|
{'name': name, 'in': 'query', 'required': False, 'schema': schema} for name, schema in (
|
|
('query', {'type': 'string'}), ('barcode', {'type': 'string'}), ('brand', {'type': 'string'}),
|
|
('package_quantity', {'type': 'number'}), ('package_unit', {'type': 'string', 'enum': ['g', 'ml']}),
|
|
('limit', {'type': 'integer', 'minimum': 1, 'maximum': 20}),
|
|
('include_open_food_facts', {'type': 'boolean'}))]
|
|
document['paths']['/kitchen/import-groceries/']['post']['parameters'] = [{
|
|
'name': 'Idempotency-Key', 'in': 'header', 'required': True,
|
|
'schema': {'type': 'string', 'maxLength': 128},
|
|
}]
|
|
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)
|