api documentation basics

cookbook/templates/api_info.html

@@ -0,0 +1,16 @@
+{% extends "base.html" %}
+{% load static %}
+{% load i18n %}
+
+{% block title %}{% trans "API Documentation" %}{% endblock %}
+
+{% block extra_head %}
+
+{% endblock %}
+
+{% block content_fluid %}
+
+    <redoc spec-url='{% url 'openapi-schema' %}'></redoc>
+    <script src="{% static 'js/redoc.standalone.js' %}"></script>
+
+{% endblock %}

cookbook/templates/base.html

@@ -139,6 +139,9 @@
                         <div class="dropdown-divider"></div>
                         <a class="dropdown-item" href="{% url 'docs_markdown' %}"><i
                                 class="fab fa-markdown fa-fw"></i> {% trans 'Markdown Help' %}</a>
+                        <a class="dropdown-item" href="{% url 'docs_api' %}"><i
+                                class="fas fa-terminal fa-fw"></i> {% trans 'API Documentation' %}</a>
+
                         <a class="dropdown-item" href="https://github.com/vabene1111/recipes"><i
                                 class="fab fa-github fa-fw"></i> {% trans 'GitHub' %}</a>
                         <div class="dropdown-divider"></div>
@@ -175,6 +178,11 @@
     {% endblock %}
 </div>
 
+<div class="container-fluid">
+    {% block content_fluid %}
+    {% endblock %}
+</div>
+
 {% block script %}
 {% endblock script %}
 

cookbook/urls.py

@@ -2,6 +2,7 @@ from pydoc import locate
 
 from django.urls import path, include
 from rest_framework import routers
+from rest_framework.schemas import get_schema_view
 
 from .views import *
 from cookbook.views import api, import_export
@@ -62,9 +63,16 @@ urlpatterns = [
     path('dal/unit/', dal.UnitAutocomplete.as_view(), name='dal_unit'),
 
     path('docs/markdown/', views.markdown_info, name='docs_markdown'),
+    path('docs/api/', views.api_info, name='docs_api'),
+
+    path('openapi', get_schema_view(
+        title="Django Recipes",
+        version=VERSION_NUMBER
+    ), name='openapi-schema'),
 
     path('api/', include((router.urls, 'api'))),
-    path('api-auth/', include('rest_framework.urls', namespace='rest_framework'))
+    path('api-auth/', include('rest_framework.urls', namespace='rest_framework')),
+
 ]
 
 generic_models = (Recipe, RecipeImport, Storage, RecipeBook, MealPlan, SyncLog, Sync, Comment, RecipeBookEntry, Keyword, Ingredient)

cookbook/views/api.py

@@ -22,6 +22,11 @@ from cookbook.serializer import MealPlanSerializer, MealTypeSerializer, RecipeSe
 
 
 class UserNameViewSet(viewsets.ModelViewSet):
+    """
+    list:
+    optional parameters
+    - **filter_list**: array of user id's to get names for
+    """
     queryset = User.objects.all()
     serializer_class = UserNameSerializer
     permission_classes = [permissions.IsAuthenticated]
@@ -40,6 +45,11 @@ class UserNameViewSet(viewsets.ModelViewSet):
 
 
 class MealPlanViewSet(viewsets.ModelViewSet):
+    """
+    list:
+    optional parameters
+    - **html_week**: filter for a calendar week (format 2020-W24 as html input type week)
+    """
     queryset = MealPlan.objects.all()
     serializer_class = MealPlanSerializer
     permission_classes = [permissions.IsAuthenticated]
@@ -54,6 +64,10 @@ class MealPlanViewSet(viewsets.ModelViewSet):
 
 
 class MealTypeViewSet(viewsets.ModelViewSet):
+    """
+    list:
+    returns list of meal types created by the requesting user ordered by the order field
+    """
     queryset = MealType.objects.order_by('order').all()
     serializer_class = MealTypeSerializer
     permission_classes = [permissions.IsAuthenticated]
@@ -64,6 +78,12 @@ class MealTypeViewSet(viewsets.ModelViewSet):
 
 
 class RecipeViewSet(viewsets.ModelViewSet):
+    """
+    list:
+    optional parameters
+    - **query**: search a recipe for a string contained in the recipe name (case in-sensitive)
+    - **limit**: limits the amount of returned recipes
+    """
     queryset = Recipe.objects.all()
     serializer_class = RecipeSerializer
     permission_classes = [permissions.IsAuthenticated]

cookbook/views/views.py

@@ -295,3 +295,8 @@ def setup(request):
 
 def markdown_info(request):
     return render(request, 'markdown_info.html', {})
+
+
+@group_required('user')
+def api_info(request):
+    return render(request, 'api_info.html', {})

requirements.txt

@@ -20,4 +20,5 @@ simplejson==3.17.0
 six==1.15.0
 webdavclient3==3.14.4
 whitenoise==5.1.0
-icalendar==4.0.6
+icalendar==4.0.6
+pyyaml===5.3.1