From 43c6d7168b77ed1f8d0837e0a648aa1a0094a8cc Mon Sep 17 00:00:00 2001
From: Mark Hoekveen <mark@hoekveen.net>
Date: Sun, 13 Jul 2025 11:31:11 +0200
Subject: [PATCH] openapi defs for album and artist

---
 backend/playlist/serializers/album.py  | 35 ++++++++++++++++++++++++++
 backend/playlist/serializers/artist.py | 21 ++++++++++++++++
 backend/playlist/views/api/album.py    |  3 +++
 backend/playlist/views/api/artist.py   |  3 +++
 4 files changed, 62 insertions(+)

diff --git a/backend/playlist/serializers/album.py b/backend/playlist/serializers/album.py
index 43c2413..abd0b38 100644
--- a/backend/playlist/serializers/album.py
+++ b/backend/playlist/serializers/album.py
@@ -1,7 +1,42 @@
+from os import extsep
 from django.db.models.functions import Extract
 from playlist.models import Album
 from rest_framework import serializers
+from drf_spectacular.utils import extend_schema_serializer, OpenApiExample
 
+@extend_schema_serializer(
+    examples = [
+        OpenApiExample(
+            name='Album Example',
+            value = {
+                "url": "http://muzak.hoekveen.net/api/album/7MejfRSNnrpcLZIxkeZDqR",
+                "name": "Leftoverture (Expanded Edition)",
+                "album_type": "album",
+                "total_tracks": 10,
+                "image": "http://127.0.0.1:8001/albums/Leftoverture_Expanded_Edition.png",
+                "image_url": "https://i.scdn.co/image/ab67616d0000b2731be40e44db112e123e5e8b51",
+                "artists": [
+                    "http://127.0.0.1:8001/api/artist/2hl0xAkS2AIRAu23TVMBG1"
+                ]
+            }
+        ),
+        OpenApiExample(
+            name = 'Multiple artist single',
+            value = {
+                "url": "http://127.0.0.1:8001/api/album/1pHD8AFu4z1CvuTPjZFOFi",
+                "name": "ラビリンス",
+                "album_type": "single",
+                "total_tracks": 4,
+                "image": None,
+                "image_url": "https://i.scdn.co/image/ab67616d0000b2731607d3aa3a69ca0e1ffbe26b",
+                "artists": [
+                    "http://127.0.0.1:8001/api/artist/4ZX8Wr8KHHrW7radu6IwYG",
+                    "http://127.0.0.1:8001/api/artist/4d2zOuYJHBPJTpVblHEKJb"
+                ]
+            }
+        )
+    ]
+)
 class AlbumSerializer(serializers.HyperlinkedModelSerializer):
     class Meta:
         model = Album
diff --git a/backend/playlist/serializers/artist.py b/backend/playlist/serializers/artist.py
index 6742b58..53d3fbc 100644
--- a/backend/playlist/serializers/artist.py
+++ b/backend/playlist/serializers/artist.py
@@ -1,6 +1,27 @@
 from playlist.models import Artist
 from rest_framework import serializers
+from drf_spectacular.utils import extend_schema_serializer, OpenApiExample
 
+@extend_schema_serializer(
+    examples=[
+        OpenApiExample(
+            'Daft Punk',
+            value = {
+                "id": "4tZwfgrHOc3mvqYlEYSvVi",
+                "name": "Daft Punk",
+                "url": "http://127.0.0.1:8001/api/artist/4tZwfgrHOc3mvqYlEYSvVi"
+            }
+        ),
+        OpenApiExample(
+            'コリッキー',
+            value = {
+                "id": "307y5sbPNvRpXjBcZgS25q",
+                "name": "コリッキー",
+                "url": "http://127.0.0.1:8001/api/artist/307y5sbPNvRpXjBcZgS25q"
+            }
+        )
+    ]
+)
 class ArtistSerializer(serializers.HyperlinkedModelSerializer):
     class Meta:
         model = Artist
diff --git a/backend/playlist/views/api/album.py b/backend/playlist/views/api/album.py
index 5c9ba25..1345087 100644
--- a/backend/playlist/views/api/album.py
+++ b/backend/playlist/views/api/album.py
@@ -2,14 +2,17 @@ from rest_framework.views import APIView
 from rest_framework.response import Response
 from playlist.models import Album
 from playlist.serializers import AlbumSerializer
+from drf_spectacular.utils import extend_schema
 
 class AlbumListView(APIView):
+    @extend_schema(responses={200: AlbumSerializer(many=True)})
     def get(self, request):
         albums = Album.objects.all()
         serializer = AlbumSerializer(albums, many=True, context={'request': request})
         return Response(serializer.data)
 
 class AlbumDetailView(APIView):
+    @extend_schema(responses={200: AlbumSerializer})
     def get(self, request, id):
         album = Album.objects.get(pk=id)
         serializer = AlbumSerializer(album, context={'request': request})
diff --git a/backend/playlist/views/api/artist.py b/backend/playlist/views/api/artist.py
index 89185df..ccb03e5 100644
--- a/backend/playlist/views/api/artist.py
+++ b/backend/playlist/views/api/artist.py
@@ -3,13 +3,16 @@ from rest_framework.views import APIView
 from rest_framework.response import Response
 from playlist.models import Artist
 from playlist.serializers import ArtistSerializer
+from drf_spectacular.utils import extend_schema
 
+@extend_schema(responses={200: ArtistSerializer(many=True)})
 class ArtistListView(APIView):
     def get(self, request):
         artists = Artist.objects.all()
         serializer = ArtistSerializer(artists, many=True, context={'request': request})
         return Response(serializer.data)
 
+@extend_schema(responses={200: ArtistSerializer})
 class ArtistDetailView(APIView):
     def get(self, request, id):
         artist = Artist.objects.get(pk=id)