290 lines
19 KiB
Python
290 lines
19 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'},
|
|
}}
|
|
BULK_INVENTORY_UPDATE = {'type': 'object', 'required': ['items'], 'properties': {
|
|
'items': {'type': 'array', 'minItems': 1, 'maxItems': 20, 'items': {'type': 'object',
|
|
'required': ['item_id', 'changes'], 'properties': {'item_id': {'type': 'string', 'format': 'uuid'},
|
|
'changes': INVENTORY, 'expected_updated_at': {'type': 'string', 'format': 'date-time'}}}},
|
|
'dry_run': {'type': 'boolean', 'default': True}, 'atomic': {'type': 'boolean', 'default': False},
|
|
}}
|
|
BULK_INVENTORY_DELETE = {'type': 'object', 'required': ['item_ids'], 'properties': {
|
|
'item_ids': {'type': 'array', 'minItems': 1, 'maxItems': 20, 'items': {'type': 'string', 'format': 'uuid'}},
|
|
'dry_run': {'type': 'boolean', 'default': True}, 'confirm': {'type': 'boolean', 'default': False},
|
|
'atomic': {'type': 'boolean', 'default': False},
|
|
}}
|
|
UPLOAD = {'type': 'object', 'required': ['image'], 'properties': {
|
|
'image': {'type': 'string', 'format': 'binary'}, 'caption': {'type': 'string'},
|
|
}}
|
|
HYDRATION_MANUAL = {'type': 'object', 'properties': {
|
|
'amount_ml': {'type': 'string', 'description': 'Positive decimal, at most 3000 ml'},
|
|
'beverage_type': {'type': 'string'},
|
|
'recorded_at': {'type': 'string', 'format': 'date-time',
|
|
'description': 'Defaults to now; naive values use the user time zone'},
|
|
}}
|
|
HYDRATION_SETTINGS = {'type': 'object', 'properties': {
|
|
'daily_water_goal_ml': {'type': 'integer', 'minimum': 250, 'maximum': 10000},
|
|
**{name: {'type': 'boolean'} for name in (
|
|
'auto_count_food_drinks', 'include_liquid_foods', 'show_hydration_breakdown',
|
|
'allow_manual_hydration_adjustments')},
|
|
'hydration_beverage_rules': {'type': 'object', 'description':
|
|
'Optional beverage type rules with enabled and factor (0 to 1) keys.'},
|
|
}}
|
|
RECIPE = {'type': 'object', 'properties': {
|
|
'title': {'type': 'string', 'maxLength': 180},
|
|
'description': {'type': 'string'}, 'instructions_markdown': {'type': 'string'},
|
|
'notes_markdown': {'type': 'string'}, 'category': {'type': 'string'},
|
|
'tags': {'type': 'array', 'items': {'type': 'string'}},
|
|
'default_servings': {'type': 'string', 'description': 'Positive decimal'},
|
|
'yield_amount': {'type': ['string', 'null']},
|
|
'yield_unit': {'type': ['string', 'null'], 'enum': ['g', 'ml', None]},
|
|
'preparation_minutes': {'type': 'integer', 'minimum': 0},
|
|
'cooking_minutes': {'type': 'integer', 'minimum': 0},
|
|
'status': {'type': 'string', 'enum': ['draft', 'published']},
|
|
'is_favourite': {'type': 'boolean'},
|
|
}}
|
|
RECIPE_INGREDIENT = {'type': 'object', 'properties': {
|
|
'name': {'type': 'string'}, 'quantity': {'type': 'string', 'description': 'Positive decimal'},
|
|
'unit': {'type': 'string', 'enum': ['g', 'kg', 'ml', 'L', 'pieces', 'tsp', 'tbsp', 'portions']},
|
|
'amount_per_unit': {'type': ['string', 'null']},
|
|
'amount_per_unit_unit': {'type': ['string', 'null'], 'enum': ['g', 'ml', None]},
|
|
'inventory_product_id': {'type': ['string', 'null'], 'format': 'uuid'},
|
|
'nutrition_product_id': {'type': ['string', 'null'], 'format': 'uuid'},
|
|
'preparation_note': {'type': 'string'}, 'is_optional': {'type': 'boolean'},
|
|
'display_order': {'type': 'integer', 'minimum': 0},
|
|
}}
|
|
RECIPE_ANALYSIS = {'type': 'object', 'properties': {
|
|
'servings': {'type': 'string', 'description': 'Prepared servings; defaults to the recipe'},
|
|
'include_optional': {'type': 'boolean'},
|
|
'substitutions': {'type': 'object', 'additionalProperties': {'type': 'string'}},
|
|
}}
|
|
STRESS = {'type': 'object', 'required': ['score'], 'properties': {
|
|
'score': {'type': 'integer', 'minimum': 0, 'maximum': 10},
|
|
'recorded_at': {'type': 'string', 'format': 'date-time', 'description': 'Defaults to now; naive times use the user time zone'},
|
|
'timing': {'type': 'string', 'enum': ['anytime', 'before_sleep', 'after_waking']},
|
|
'note': {'type': 'string', 'maxLength': 2000},
|
|
'tags': {'type': 'array', 'maxItems': 12, 'items': {'type': 'string', 'maxLength': 40}},
|
|
'symptoms': {'type': 'array', 'items': {'type': 'string', 'enum': ['tension', 'headache', 'fatigue', 'restlessness']}},
|
|
}}
|
|
DREAM = {'type': 'object', 'required': ['wake_up_date', 'title', 'narrative'], 'properties': {
|
|
'wake_up_date': {'type': 'string', 'format': 'date', 'description': 'Local date on waking; matches Health > Sleep'},
|
|
'dreamed_at': {'type': ['string', 'null'], 'format': 'date-time'},
|
|
'title': {'type': 'string', 'maxLength': 160},
|
|
'narrative': {'type': 'string', 'maxLength': 20000},
|
|
'interpretation': {'type': 'string', 'maxLength': 4000},
|
|
'tags': {'type': 'array', 'maxItems': 12, 'items': {'type': 'string'}},
|
|
'emotions': {'type': 'array', 'maxItems': 12, 'items': {'type': 'string'}},
|
|
'vividness': {'type': ['integer', 'null'], 'minimum': 0, 'maximum': 10},
|
|
'is_nightmare': {'type': 'boolean'},
|
|
'after_waking_notes': {'type': 'string', 'maxLength': 4000},
|
|
'append_narrative': {'type': 'string', 'description': 'PATCH only; requires Idempotency-Key'},
|
|
'append_after_waking_notes': {'type': 'string', 'description': 'PATCH only; requires Idempotency-Key'},
|
|
}}
|
|
|
|
|
|
@require_GET
|
|
def schema(request):
|
|
document = {
|
|
'openapi': '3.1.0', 'info': {'title': 'TaskNest API', 'version': '1.0.0'},
|
|
'servers': [{'url': '/api/v1'}],
|
|
'components': {'securitySchemes': {'bearerToken': {'type': 'http', 'scheme': 'bearer'}}},
|
|
'paths': {
|
|
'/dreams/': {
|
|
'get': operation('Search own dreams by keywords, tags, and wake-up date', 'journal:read'),
|
|
'post': operation('Create own dream with optional Idempotency-Key', 'journal:write', DREAM),
|
|
},
|
|
'/dreams/{id}/': {
|
|
'get': operation('Read own dream', 'journal:read'),
|
|
'patch': operation('Update or append to own dream; append requires Idempotency-Key', 'journal:write', DREAM),
|
|
'delete': operation('Delete own dream', 'journal:write'),
|
|
},
|
|
'/stress/': {
|
|
'get': operation('Search own stress check-ins by text, date, and timing', 'journal:read'),
|
|
'post': operation('Create own stress check-in with optional Idempotency-Key', 'journal:write', STRESS),
|
|
},
|
|
'/stress/{id}/': {
|
|
'get': operation('Read own stress check-in', 'journal:read'),
|
|
'patch': operation('Update own stress check-in', 'journal:write', STRESS),
|
|
'delete': operation('Delete own stress check-in', 'journal:write'),
|
|
},
|
|
'/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/bulk-update/': {'post': operation('Preview or update up to 20 inventory items; execution requires Idempotency-Key',
|
|
'inventory:write', BULK_INVENTORY_UPDATE)},
|
|
'/kitchen/bulk-delete/': {'post': operation('Preview or archive up to 20 inventory items; execution requires confirm and Idempotency-Key',
|
|
'inventory:write', BULK_INVENTORY_DELETE)},
|
|
'/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')},
|
|
'/hydration/daily/': {'get': operation('Combined manual and Food Diary fluid totals for a user local date', 'food:read')},
|
|
'/hydration/manual/': {'post': operation('Create standalone fluid entry with optional Idempotency-Key', 'food:write', HYDRATION_MANUAL)},
|
|
'/hydration/manual/{id}/': {
|
|
'patch': operation('Correct own manual fluid entry', 'food:write', HYDRATION_MANUAL),
|
|
'delete': operation('Delete own manual fluid entry', 'food:write'),
|
|
},
|
|
'/hydration/settings/': {
|
|
'get': operation('Read hydration settings', 'food:read'),
|
|
'patch': operation('Update hydration settings', 'food:write', HYDRATION_SETTINGS),
|
|
},
|
|
'/recipes/': {'get': operation('Search own recipes by query, category, and limit', 'food:read')},
|
|
'/recipes/cook-later/': {
|
|
'get': operation('List Cook Later recipes with search and pagination', 'food:read'),
|
|
'post': operation('Idempotently add a visible recipe to Cook Later', 'food:write',
|
|
{'type': 'object', 'required': ['recipe_id'], 'properties': {'recipe_id': {'type': 'string'}}}),
|
|
},
|
|
'/recipes/cook-later/{id}/': {'delete': operation('Remove recipe from Cook Later', 'food:write')},
|
|
'/recipes/create/': {'post': operation('Create own recipe with optional Idempotency-Key', 'food:write', RECIPE)},
|
|
'/recipes/{id}/': {
|
|
'get': operation('Read own recipe with ingredients, subrecipes, and variations', 'food:read'),
|
|
'patch': operation('Update own recipe', 'food:write', RECIPE),
|
|
'delete': operation('Delete own recipe when no parent recipe uses it', 'food:write'),
|
|
},
|
|
'/recipes/{id}/variations/': {'post': operation('Copy own recipe as an independent variation', 'food:write',
|
|
{'type': 'object', 'properties': {'title': {'type': 'string'}}})},
|
|
'/recipes/{id}/ingredients/': {'post': operation('Add ingredient to own recipe', 'food:write', RECIPE_INGREDIENT)},
|
|
'/recipes/{id}/ingredients/{item_id}/': {
|
|
'patch': operation('Update own recipe ingredient', 'food:write', RECIPE_INGREDIENT),
|
|
'delete': operation('Remove own recipe ingredient', 'food:write'),
|
|
},
|
|
'/recipes/{id}/subrecipes/': {'post': operation('Attach an owned component recipe', 'food:write',
|
|
{'type': 'object', 'required': ['component_id'], 'properties': {
|
|
'component_id': {'type': 'string', 'format': 'uuid'}, 'quantity': {'type': 'string'},
|
|
'unit': {'type': 'string'}, 'note': {'type': 'string'},
|
|
'display_order': {'type': 'integer'}}})},
|
|
'/recipes/{id}/subrecipes/{item_id}/': {'delete': operation('Detach a component recipe', 'food:write')},
|
|
'/recipes/{id}/stock/preview/': {'post': operation('Preview inventory and issue confirmation when stock is ready',
|
|
'inventory:read', RECIPE_ANALYSIS)},
|
|
'/recipes/{id}/stock/confirm/': {'post': operation('Deduct inventory using the exact preview confirmation',
|
|
'inventory:write', {'type': 'object', 'required': ['confirmation'], 'properties': {
|
|
'confirmation': {'type': 'string'}}})},
|
|
'/recipes/stock-use/{id}/undo/': {'post': operation('Undo a safe recipe inventory deduction', 'inventory:write')},
|
|
'/recipes/{id}/log/': {'post': operation('Log consumed recipe servings without deducting stock; requires Idempotency-Key',
|
|
'food:write', {'type': 'object', 'required': ['consumed_servings', 'meal'],
|
|
'properties': {**RECIPE_ANALYSIS['properties'],
|
|
'consumed_servings': {'type': 'string'},
|
|
'meal': {'type': 'string', 'enum': ['breakfast', 'lunch', 'dinner', 'snacks']},
|
|
'date': {'type': 'string', 'format': 'date'}, 'time': {'type': 'string', 'format': 'time'}}})},
|
|
},
|
|
}
|
|
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 '{item_id}' in path:
|
|
methods.setdefault('parameters', []).append({'name': 'item_id', 'in': 'path', 'required': True,
|
|
'schema': {'type': 'integer', 'minimum': 1}})
|
|
if 'post' in methods:
|
|
methods['post']['responses']['201'] = methods['post']['responses'].pop('200')
|
|
for path in ('/kitchen/bulk-update/', '/kitchen/bulk-delete/',
|
|
'/kitchen/consumption/preview/', '/kitchen/consumption/',
|
|
'/kitchen/consumption/{id}/undo/', '/recipes/{id}/stock/preview/',
|
|
'/recipes/{id}/stock/confirm/', '/recipes/stock-use/{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']['/hydration/daily/']['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},
|
|
}]
|
|
for path in ('/kitchen/bulk-update/', '/kitchen/bulk-delete/'):
|
|
document['paths'][path]['post']['parameters'] = [{
|
|
'name': 'Idempotency-Key', 'in': 'header', 'required': False,
|
|
'description': 'Required when dry_run is false.',
|
|
'schema': {'type': 'string', 'maxLength': 128},
|
|
}]
|
|
document['paths']['/recipes/{id}/log/']['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)
|