1358 implemented api docs (#1359)

* adds drf spectacular

* adds title and project description

* adds documentation on api documentation

* RRRRuff

* added spectacular to dev deps

* changed urls.py back

* added "samfundet:schema" to schema urls

* repair poetry.lock

* removes alias for generating schema, deleted schema.

* removes commend

* moved spectacular url patterns

README.md

@@ -10,6 +10,7 @@
 - [Technologies used on Samf4 🤖](/docs/technical/Samf4Tech.md)
 - [Project Specific Commands](/docs/docker-project-specific-commands.md)
 - [Useful Docker aliases](/docs/docker-project-specific-commands.md)
+- [🌐 API documentation](/docs/api-docs.md)
 
 ## Installation
 

backend/pyproject.toml

@@ -166,6 +166,7 @@ debugpy = "1.*"
 requests = "2.*"
 pytest = "8.*"
 pytest-django = "4.*"
+drf-spectacular = "0.27.*"
 
 [build-system]
 requires = ["poetry-core"]

backend/root/settings/base.py

@@ -87,6 +87,7 @@
     'corsheaders',
     'root',  # Register to enable management.commands.
     'samfundet',
+    'drf_spectacular',
 ]
 
 MIDDLEWARE = [
@@ -178,9 +179,18 @@
         'root.custom_classes.permission_classes.SuperUserPermission',
         # 'root.custom_classes.permission_classes.CustomDjangoObjectPermissions',
     ],
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
 }
 ### End: DRF ###
 
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'Samfundet4 API',
+    'DESCRIPTION': 'Samfundet4 is the new webpage of Studentersamfundet in Trondhjem',
+    'VERSION': '1.0.0',
+    'SERVE_INCLUDE_SCHEMA': False,
+    # OTHER SETTINGS
+}
+
 ### django-guardian ###
 INSTALLED_APPS += [
     'guardian',

backend/samfundet/urls.py

@@ -1,14 +1,15 @@
 # imports
 from __future__ import annotations
 
+from drf_spectacular.views import SpectacularAPIView, SpectacularRedocView, SpectacularSwaggerView
+
 from rest_framework import routers
 
 from django.urls import path, include
 
 from . import views
 
 # End: imports -----------------------------------------------------------------
-
 router = routers.DefaultRouter()
 router.register('images', views.ImageView, 'images')
 router.register('tags', views.TagView, 'tags')
@@ -52,6 +53,9 @@
 
 urlpatterns = [
     path('api/', include(router.urls)),
+    path('schema/', SpectacularAPIView.as_view(), name='schema'),
+    path('schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='samfundet:schema'), name='swagger_ui'),
+    path('schema/redoc/', SpectacularRedocView.as_view(url_name='samfundet:schema'), name='redoc'),
     path('csrf/', views.CsrfView.as_view(), name='csrf'),
     path('login/', views.LoginView.as_view(), name='login'),
     path('register/', views.RegisterView.as_view(), name='register'),

docs/api-docs.md

@@ -0,0 +1,19 @@
+# API docs
+
+API docs are generated by [drf-spectacular](https://drf-spectacular.readthedocs.io/en/latest/readme.html).
+
+API documentation is available as two different interfaces:
+
+[Swagger-UI](http://localhost:8000/schema/swagger-ui/#/) or [Redoc](http://localhost:8000/schema/redoc/)
+
+
+
+🐋 _When backend server is running_
+
+## API schema file
+
+If you want a schema file for the API you can go to [http://localhost:8000/schema/](http://localhost:8000/schema/).
+
+A schema file will be downloaded which can be used for multiple purposes, like sharing API documentation, or to generate code for recreating or testing the API.
+
+> 💡 Note: You might encounter some error messages during this process. These errors are typically related to drf-spectacular not being able to parse certain views in views.py. However, the tool will still attempt to generate the documentation, though the results might not be fully comprehensive.