From 5a56245218110bab27e57919519ec22b1fedbdd8 Mon Sep 17 00:00:00 2001 From: Rudi Date: Tue, 13 Oct 2026 19:26:56 +0200 Subject: [PATCH] Update API Doc --- app/api/docs/api/route.ts | 17 + app/api/docs/route.ts | 1 - app/api/songbooks/[songBookId]/route.ts | 84 +- .../[songBookId]/songs/[songId]/route.ts | 74 +- app/api/songbooks/[songBookId]/songs/route.ts | 45 +- app/api/songbooks/route.ts | 68 +- app/api/songs/[songId]/route.ts | 75 +- app/api/songs/route.ts | 76 +- app/api/stream/route.ts | 100 +- src/generated/openapi.json | 885 +++++++++++++++--- 10 files changed, 1196 insertions(+), 229 deletions(-) delete mode 100644 app/api/docs/route.ts diff --git a/app/api/docs/api/route.ts b/app/api/docs/api/route.ts index 6d6f685..e548129 100644 --- a/app/api/docs/api/route.ts +++ b/app/api/docs/api/route.ts @@ -1,5 +1,22 @@ // @/app/api/docs/api/routes.ts + +/** + * @openapi + * /api/docs/api: + * get: + * summary: OpenAPI-Spezifikation abrufen + * tags: + * - Docs + * description: Gibt die vollständige OpenAPI-JSON-Spezifikation der API zurück. + * responses: + * 200: + * description: Erfolgreich generierte OpenAPI-Spezifikation. + * content: + * application/json: + * schema: + * type: object + */ import { NextResponse } from 'next/server'; import spec from '@/src/generated/openapi.json'; diff --git a/app/api/docs/route.ts b/app/api/docs/route.ts deleted file mode 100644 index 6f11f21..0000000 --- a/app/api/docs/route.ts +++ /dev/null @@ -1 +0,0 @@ -// @/app/api/docs/routes.ts diff --git a/app/api/songbooks/[songBookId]/route.ts b/app/api/songbooks/[songBookId]/route.ts index 5db3239..8a4ecdd 100644 --- a/app/api/songbooks/[songBookId]/route.ts +++ b/app/api/songbooks/[songBookId]/route.ts @@ -1,3 +1,5 @@ +// @/app/api/songbooks/[songBookId]/route.ts + import { NextResponse } from "next/server"; import { getSongBookById, updateSongBook, deleteSongBook } from "@/lib/db/songbook"; @@ -9,38 +11,51 @@ interface RouteParams { /** * @openapi - * /api/songbooks/{id}: + * /api/songbooks/{songBookId}: * get: - * summary: Einzelnen Songbook abrufen + * summary: Einzelnes Songbook abrufen * tags: * - Songbooks * parameters: * - in: path - * name: id + * name: songBookId * required: true * schema: * type: integer * description: Die ID des Songbooks + * example: 1 * responses: * 200: * description: Songbook erfolgreich gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBook' * 400: * description: Ungültige Songbook-ID + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Songbook nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ - - export async function GET(_request: Request, { params }: RouteParams) { try { const { songBookId } = await params; - const res = await getSongBookById(parseInt(songBookId)); - if (!res.success) { return NextResponse.json({ message: res.error }, { status: res.status }); } @@ -58,33 +73,57 @@ export async function GET(_request: Request, { params }: RouteParams) { /** * @openapi - * /api/songbooks/{id}: + * /api/songbooks/{songBookId}: * patch: * summary: Songbook aktualisieren * tags: * - Songbooks * parameters: * - in: path - * name: id + * name: songBookId * required: true * schema: * type: integer * description: Die ID des Songbooks + * example: 1 * requestBody: * required: true * content: * application/json: * schema: * type: object + * properties: + * title: + * type: string + * example: "Feiert Jesus 1" + * language: + * type: string + * example: "DE" * responses: * 200: * description: Songbook erfolgreich aktualisiert + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBook' * 400: * description: Ungültige Parameter oder Daten + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Songbook nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function PATCH(request: Request, { params }: RouteParams) { try { @@ -100,7 +139,7 @@ export async function PATCH(request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songbookinfos" }, + { error: "Fehler beim Aktualisieren des Songbooks" }, { status: 500 } ); } @@ -109,27 +148,44 @@ export async function PATCH(request: Request, { params }: RouteParams) { /** * @openapi - * /api/songbooks/{id}: + * /api/songbooks/{songBookId}: * delete: * summary: Songbook löschen * tags: * - Songbooks * parameters: * - in: path - * name: id + * name: songBookId * required: true * schema: * type: integer * description: Die ID des Songbooks + * example: 1 * responses: * 200: - * description: Songbook erfolgreich gelöscht + * description: Songbook erfolgreich gelöscht (gibt das gelöschte Songbook zurück) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBook' * 400: * description: Ungültige Songbook-ID + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Songbook nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function DELETE(_request: Request, { params }: RouteParams) { try { @@ -144,7 +200,7 @@ export async function DELETE(_request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songbookinfos" }, + { error: "Fehler beim Löschen des Songbooks" }, { status: 500 } ); } diff --git a/app/api/songbooks/[songBookId]/songs/[songId]/route.ts b/app/api/songbooks/[songBookId]/songs/[songId]/route.ts index 058356f..16bcf8b 100644 --- a/app/api/songbooks/[songBookId]/songs/[songId]/route.ts +++ b/app/api/songbooks/[songBookId]/songs/[songId]/route.ts @@ -1,3 +1,5 @@ +// @/app/api/songbooks/[songBookId]/songs/[songId]/route.ts + import { NextResponse } from "next/server"; import { addSongToBook, updateSongInBook, removeSongFromBook } from "@/lib/db/songbooksongs"; @@ -14,7 +16,7 @@ interface RouteParams { * post: * summary: Song zu Liederbuch hinzufügen * tags: - * - Songbook + * - Songbooks * parameters: * - in: path * name: songBookId @@ -22,12 +24,14 @@ interface RouteParams { * schema: * type: integer * description: Die ID des Liederbuchs + * example: 1 * - in: path * name: songId * required: true * schema: * type: integer * description: Die ID des Songs + * example: 1 * requestBody: * required: true * content: @@ -44,12 +48,28 @@ interface RouteParams { * responses: * 200: * description: Song erfolgreich zugewiesen + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBookEntry' * 400: * description: Ungültige Parameter oder fehlende Songnummer + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 409: * description: Songnummer bereits vergeben oder Song existiert bereits im Buch + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function POST(request: Request, { params }: RouteParams) { try { @@ -68,7 +88,7 @@ export async function POST(request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songbookinfos" }, + { error: "Fehler beim Zuweisen des Songs" }, { status: 500 } ); } @@ -81,7 +101,7 @@ export async function POST(request: Request, { params }: RouteParams) { * patch: * summary: Songnummer eines Songs im Liederbuch aktualisieren * tags: - * - Songbook + * - Songbooks * parameters: * - in: path * name: songBookId @@ -89,12 +109,14 @@ export async function POST(request: Request, { params }: RouteParams) { * schema: * type: integer * description: Die ID des Liederbuchs + * example: 1 * - in: path * name: songId * required: true * schema: * type: integer * description: Die ID des Songs + * example: 1 * requestBody: * required: true * content: @@ -111,14 +133,34 @@ export async function POST(request: Request, { params }: RouteParams) { * responses: * 200: * description: Songnummer erfolgreich aktualisiert + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBookEntry' * 400: * description: Ungültige Parameter oder fehlende Daten + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Zuweisung nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 409: * description: Neue Songnummer bereits vergeben + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function PATCH(request: Request, { params }: RouteParams) { try { @@ -134,7 +176,7 @@ export async function PATCH(request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songbookinfos" }, + { error: "Fehler beim Aktualisieren der Songnummer" }, { status: 500 } ); } @@ -147,7 +189,7 @@ export async function PATCH(request: Request, { params }: RouteParams) { * delete: * summary: Song aus Liederbuch entfernen * tags: - * - Songbook + * - Songbooks * parameters: * - in: path * name: songBookId @@ -155,21 +197,39 @@ export async function PATCH(request: Request, { params }: RouteParams) { * schema: * type: integer * description: Die ID des Liederbuchs + * example: 1 * - in: path * name: songId * required: true * schema: * type: integer * description: Die ID des Songs + * example: 1 * responses: * 200: - * description: Song erfolgreich aus dem Liederbuch entfernt + * description: Song erfolgreich aus dem Liederbuch entfernt (gibt die entfernte Zuweisung zurück) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBookEntry' * 400: * description: Ungültige Parameter + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Zuweisung nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function DELETE(_request: Request, { params }: RouteParams) { try { @@ -185,7 +245,7 @@ export async function DELETE(_request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songbookinfos" }, + { error: "Fehler beim Entfernen des Songs" }, { status: 500 } ); } diff --git a/app/api/songbooks/[songBookId]/songs/route.ts b/app/api/songbooks/[songBookId]/songs/route.ts index b6640a3..8802a8a 100644 --- a/app/api/songbooks/[songBookId]/songs/route.ts +++ b/app/api/songbooks/[songBookId]/songs/route.ts @@ -1,3 +1,5 @@ +// @/app/api/songbooks/[songBookId]/songs/route.ts + import { NextResponse } from "next/server"; import { getSongByNumber } from "@/lib/db/songbooksongs"; @@ -9,27 +11,58 @@ interface RouteParams { /** * @openapi - * /api/songbooks/{id}/songs: + * /api/songbooks/{songBookId}/songs: * get: * summary: Einen Song nach Nummer in einem Songbook suchen * tags: - * - Songbook + * - Songbooks * parameters: * - in: path - * name: id + * name: songBookId * required: true * schema: * type: integer * description: Die ID des Songbooks + * example: 1 + * - in: query + * name: number + * required: true + * schema: + * type: string + * description: Die Nummer des Songs im Songbook + * example: "123" + * - in: query + * name: n + * required: false + * schema: + * type: string + * description: Alias für `number` + * example: "123" * responses: * 200: - * description: Songbook erfolgreich gefunden + * description: Song im Songbook erfolgreich gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/SongBookEntry' * 400: - * description: Ungültige Songbook-ID + * description: Ungültige Songbook-ID oder fehlender number-Parameter + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: - * description: Songbook nicht gefunden + * description: Songbook oder Song nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function GET(request: Request, { params }: RouteParams) { try { diff --git a/app/api/songbooks/route.ts b/app/api/songbooks/route.ts index 8273caa..c33d736 100644 --- a/app/api/songbooks/route.ts +++ b/app/api/songbooks/route.ts @@ -1,22 +1,45 @@ -// @wikiCategory: Liederbücher +// @/app/api/songbooks/route.ts import { NextResponse } from "next/server"; import { getSongBooks, searchSongBooksByTitle, createSongBook } from "@/lib/db/songbook"; - - /** * @openapi * /api/songbooks: * get: - * summary: Get all songbooks + * summary: Get all songbooks or search songbooks by title + * tags: + * - Songbooks + * parameters: + * - in: query + * name: query + * required: false + * schema: + * type: string + * description: Search term for the songbook title + * example: "Feiert Jesus" + * - in: query + * name: q + * required: false + * schema: + * type: string + * description: Alias for `query` + * example: "Feiert Jesus" * responses: * 200: - * description: List of songbooks + * description: List of songbooks (filtered by title if a query is given) + * content: + * application/json: + * schema: + * type: array + * items: + * $ref: '#/components/schemas/SongBook' * 500: * description: Internal Server Error - * - * @wikiDescription: Liste aller Liederbücher abrufen + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function GET(request: Request) { try { @@ -60,6 +83,8 @@ export async function GET(request: Request) { * /api/songbooks: * post: * summary: Creates a new songbook + * tags: + * - Songbooks * requestBody: * required: true * content: @@ -68,6 +93,7 @@ export async function GET(request: Request) { * type: object * required: * - title + * - language * properties: * title: * type: string @@ -87,25 +113,25 @@ export async function GET(request: Request) { * type: boolean * example: true * songBook: - * type: object - * properties: - * id: - * type: integer - * example: 1 - * title: - * type: string - * example: "Feiert Jesus 1" - * language: - * type: string - * example: "DE" + * $ref: '#/components/schemas/SongBook' * 400: - * description: Bad Request (missing title) + * description: Bad Request (missing title or language) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 409: * description: Conflict (title already exists) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Internal Server Error - * - * @wikiDescription: Neues Liederbuch erstellen + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function POST(request: Request) { try { diff --git a/app/api/songs/[songId]/route.ts b/app/api/songs/[songId]/route.ts index d4cd497..4e27093 100644 --- a/app/api/songs/[songId]/route.ts +++ b/app/api/songs/[songId]/route.ts @@ -1,3 +1,5 @@ +// @/app/api/songs/[songId]/route.ts + import { NextResponse } from "next/server"; import { getSongById, updateSong, deleteSong } from "@/lib/db/song"; @@ -9,27 +11,44 @@ interface RouteParams { /** * @openapi - * /api/songs/{id}: + * /api/songs/{songId}: * get: * summary: Einzelnen Song abrufen * tags: * - Songs * parameters: * - in: path - * name: id + * name: songId * required: true * schema: * type: integer * description: Die ID des Songs + * example: 1 * responses: * 200: * description: Song erfolgreich gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Song' * 400: * description: Ungültige Song-ID + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Song nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function GET(_request: Request, { params }: RouteParams) { try { @@ -53,33 +72,54 @@ export async function GET(_request: Request, { params }: RouteParams) { /** * @openapi - * /api/songs/{id}: + * /api/songs/{songId}: * patch: * summary: Song aktualisieren * tags: * - Songs * parameters: * - in: path - * name: id + * name: songId * required: true * schema: * type: integer * description: Die ID des Songs + * example: 1 * requestBody: * required: true * content: * application/json: * schema: * type: object + * properties: + * title: + * type: string + * example: "Großer Gott" * responses: * 200: * description: Song erfolgreich aktualisiert + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Song' * 400: * description: Ungültige Parameter oder Daten + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Song nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function PATCH(request: Request, { params }: RouteParams) { try { @@ -95,7 +135,7 @@ export async function PATCH(request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songinfos" }, + { error: "Fehler beim Aktualisieren des Songs" }, { status: 500 } ); } @@ -104,27 +144,44 @@ export async function PATCH(request: Request, { params }: RouteParams) { /** * @openapi - * /api/songs/{id}: + * /api/songs/{songId}: * delete: * summary: Song löschen * tags: * - Songs * parameters: * - in: path - * name: id + * name: songId * required: true * schema: * type: integer * description: Die ID des Songs + * example: 1 * responses: * 200: - * description: Song erfolgreich gelöscht + * description: Song erfolgreich gelöscht (gibt den gelöschten Song zurück) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Song' * 400: * description: Ungültige Song-ID + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 404: * description: Song nicht gefunden + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function DELETE(_request: Request, { params }: RouteParams) { try { @@ -139,7 +196,7 @@ export async function DELETE(_request: Request, { params }: RouteParams) { } catch (error) { console.error("API Error:", error); return NextResponse.json( - { error: "Fehler beim Laden der Songinfos" }, + { error: "Fehler beim Löschen des Songs" }, { status: 500 } ); } diff --git a/app/api/songs/route.ts b/app/api/songs/route.ts index e2749ce..966f161 100644 --- a/app/api/songs/route.ts +++ b/app/api/songs/route.ts @@ -1,27 +1,51 @@ -// @wikiCategory: Lieder +// @/app/api/songs/route.ts import { NextResponse } from "next/server"; -import { getSongs, searchSongsByTitle, createSong, } from "@/lib/db/song"; - - +import { getSongs, searchSongsByTitle, createSong } from "@/lib/db/song"; /** * @openapi * /api/songs: * get: - * summary: Get all songs + * summary: Get all songs or search songs by title + * tags: + * - Songs + * parameters: + * - in: query + * name: query + * required: false + * schema: + * type: string + * description: Search term for the song title + * example: "Großer Gott" + * - in: query + * name: q + * required: false + * schema: + * type: string + * description: Alias for `query` + * example: "Großer Gott" * responses: * 200: - * description: List of songs + * description: List of songs (filtered by title if a query is given) + * content: + * application/json: + * schema: + * type: array + * items: + * $ref: '#/components/schemas/Song' * 500: * description: Internal Server Error + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function GET(request: Request) { try { const { searchParams } = new URL(request.url); const query = searchParams.get("query") || searchParams.get("q"); - if (query) { const res = await searchSongsByTitle(query/*, 20*/); // You can enter a limit (default: 20) @@ -42,7 +66,7 @@ export async function GET(request: Request) { return NextResponse.json(res.songs, { status: res.status }); } catch (error) { - console.error("POST /api/songs error:", error); + console.error("GET /api/songs error:", error); return NextResponse.json( { message: "Internal Server Error" }, { status: 500 } @@ -50,12 +74,13 @@ export async function GET(request: Request) { } } - /** * @openapi * /api/songs: * post: * summary: Creates a new song + * tags: + * - Songs * requestBody: * required: true * content: @@ -63,14 +88,14 @@ export async function GET(request: Request) { * schema: * type: object * required: - * - name + * - title * properties: - * name: + * title: * type: string * example: "Großer Gott" * responses: * 201: - * description: Songbook successfully created + * description: Song successfully created * content: * application/json: * schema: @@ -79,21 +104,26 @@ export async function GET(request: Request) { * success: * type: boolean * example: true - * songBook: - * type: object - * properties: - * id: - * type: integer - * example: 1 - * title: - * type: string - * example: "Großer Gott" + * song: + * $ref: '#/components/schemas/Song' * 400: - * description: Bad Request (missing name) + * description: Bad Request (missing title) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 409: * description: Conflict (title already exists) + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' * 500: * description: Internal Server Error + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/Error' */ export async function POST(request: Request) { try { @@ -101,7 +131,7 @@ export async function POST(request: Request) { if (!data.title) { return NextResponse.json( - { message: "Field 'title' is required"}, + { message: "Field 'title' is required" }, { status: 400 } ); } diff --git a/app/api/stream/route.ts b/app/api/stream/route.ts index 8922136..a77609f 100644 --- a/app/api/stream/route.ts +++ b/app/api/stream/route.ts @@ -1,7 +1,22 @@ -// @wikiCategory: Stream +// @/app/api/stream/route.ts import { NextResponse } from "next/server"; +/** + * @openapi + * components: + * schemas: + * StreamError: + * type: object + * properties: + * success: + * type: boolean + * example: false + * error: + * type: string + * example: "Fields incomplete!" + */ + let currentSong = { number: "", @@ -11,7 +26,23 @@ let currentSong = { const clients = new Set(); -// @wikiDescription: Akutell gestreamtes Lied abrufen +/** + * @openapi + * /api/stream: + * get: + * summary: Aktuell gestreamtes Lied abrufen (Server-Sent Events) + * description: Öffnet einen SSE-Stream. Beim Verbinden wird das aktuelle Lied gesendet (falls gesetzt), danach bei jeder Änderung ein neues Event. + * tags: + * - Stream + * responses: + * 200: + * description: Event-Stream mit dem aktuellen Lied + * content: + * text/event-stream: + * schema: + * type: string + * example: 'data: {"number":"104a","song":"Großer Gott","songbook":"Feiert Jesus 1"}' + */ export async function GET() { let controllerRef: ReadableStreamDefaultController; @@ -38,7 +69,70 @@ export async function GET() { }); } -// @wikiDescription: Lied zum Streamen festlegen +/** + * @openapi + * /api/stream: + * post: + * summary: Lied zum Streamen festlegen + * description: Setzt das aktuelle Lied und sendet es an alle verbundenen Stream-Clients. + * tags: + * - Stream + * requestBody: + * required: true + * content: + * application/json: + * schema: + * type: object + * required: + * - song + * - songBook + * - number + * properties: + * song: + * type: string + * example: "Großer Gott" + * songBook: + * type: string + * example: "Feiert Jesus 1" + * number: + * type: string + * example: "104a" + * responses: + * 200: + * description: Lied gesetzt und an alle Clients gesendet + * content: + * application/json: + * schema: + * type: object + * properties: + * success: + * type: boolean + * example: true + * currentSong: + * type: object + * properties: + * number: + * type: string + * example: "104a" + * song: + * type: string + * example: "Großer Gott" + * songbook: + * type: string + * example: "Feiert Jesus 1" + * 400: + * description: Felder unvollständig + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/StreamError' + * 500: + * description: Serverfehler + * content: + * application/json: + * schema: + * $ref: '#/components/schemas/StreamError' + */ export async function POST(request: Request) { try { const data = await request.json(); diff --git a/src/generated/openapi.json b/src/generated/openapi.json index 86a68dc..b469744 100644 --- a/src/generated/openapi.json +++ b/src/generated/openapi.json @@ -5,20 +5,33 @@ "version": "1.0.0" }, "paths": { - "/api/songs": { + "/api/stream": { "get": { - "summary": "Get all songs", + "summary": "Aktuell gestreamtes Lied abrufen (Server-Sent Events)", + "description": "Öffnet einen SSE-Stream. Beim Verbinden wird das aktuelle Lied gesendet (falls gesetzt), danach bei jeder Änderung ein neues Event.", + "tags": [ + "Stream" + ], "responses": { "200": { - "description": "List of songs" - }, - "500": { - "description": "Internal Server Error" + "description": "Event-Stream mit dem aktuellen Lied", + "content": { + "text/event-stream": { + "schema": { + "type": "string", + "example": "data: {\"number\":\"104a\",\"song\":\"Großer Gott\",\"songbook\":\"Feiert Jesus 1\"}" + } + } + } } } }, "post": { - "summary": "Creates a new song", + "summary": "Lied zum Streamen festlegen", + "description": "Setzt das aktuelle Lied und sendet es an alle verbundenen Stream-Clients.", + "tags": [ + "Stream" + ], "requestBody": { "required": true, "content": { @@ -26,10 +39,155 @@ "schema": { "type": "object", "required": [ - "name" + "song", + "songBook", + "number" ], "properties": { - "name": { + "song": { + "type": "string", + "example": "Großer Gott" + }, + "songBook": { + "type": "string", + "example": "Feiert Jesus 1" + }, + "number": { + "type": "string", + "example": "104a" + } + } + } + } + } + }, + "responses": { + "200": { + "description": "Lied gesetzt und an alle Clients gesendet", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": true + }, + "currentSong": { + "type": "object", + "properties": { + "number": { + "type": "string", + "example": "104a" + }, + "song": { + "type": "string", + "example": "Großer Gott" + }, + "songbook": { + "type": "string", + "example": "Feiert Jesus 1" + } + } + } + } + } + } + } + }, + "400": { + "description": "Felder unvollständig", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StreamError" + } + } + } + }, + "500": { + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StreamError" + } + } + } + } + } + } + }, + "/api/songs": { + "get": { + "summary": "Get all songs or search songs by title", + "tags": [ + "Songs" + ], + "parameters": [ + { + "in": "query", + "name": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Search term for the song title", + "example": "Großer Gott" + }, + { + "in": "query", + "name": "q", + "required": false, + "schema": { + "type": "string" + }, + "description": "Alias for `query`", + "example": "Großer Gott" + } + ], + "responses": { + "200": { + "description": "List of songs (filtered by title if a query is given)", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Song" + } + } + } + } + }, + "500": { + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "summary": "Creates a new song", + "tags": [ + "Songs" + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "title" + ], + "properties": { + "title": { "type": "string", "example": "Großer Gott" } @@ -40,7 +198,7 @@ }, "responses": { "201": { - "description": "Songbook successfully created", + "description": "Song successfully created", "content": { "application/json": { "schema": { @@ -50,18 +208,8 @@ "type": "boolean", "example": true }, - "songBook": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "example": 1 - }, - "title": { - "type": "string", - "example": "Großer Gott" - } - } + "song": { + "$ref": "#/components/schemas/Song" } } } @@ -69,18 +217,39 @@ } }, "400": { - "description": "Bad Request (missing name)" + "description": "Bad Request (missing title)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "409": { - "description": "Conflict (title already exists)" + "description": "Conflict (title already exists)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Internal Server Error" + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/api/songs/{id}": { + "/api/songs/{songId}": { "get": { "summary": "Einzelnen Song abrufen", "tags": [ @@ -89,26 +258,55 @@ "parameters": [ { "in": "path", - "name": "id", + "name": "songId", "required": true, "schema": { "type": "integer" }, - "description": "Die ID des Songs" + "description": "Die ID des Songs", + "example": 1 } ], "responses": { "200": { - "description": "Song erfolgreich gefunden" + "description": "Song erfolgreich gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Song" + } + } + } }, "400": { - "description": "Ungültige Song-ID" + "description": "Ungültige Song-ID", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Song nicht gefunden" + "description": "Song nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, @@ -120,12 +318,13 @@ "parameters": [ { "in": "path", - "name": "id", + "name": "songId", "required": true, "schema": { "type": "integer" }, - "description": "Die ID des Songs" + "description": "Die ID des Songs", + "example": 1 } ], "requestBody": { @@ -133,23 +332,57 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "title": { + "type": "string", + "example": "Großer Gott" + } + } } } } }, "responses": { "200": { - "description": "Song erfolgreich aktualisiert" + "description": "Song erfolgreich aktualisiert", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Song" + } + } + } }, "400": { - "description": "Ungültige Parameter oder Daten" + "description": "Ungültige Parameter oder Daten", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Song nicht gefunden" + "description": "Song nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, @@ -161,44 +394,118 @@ "parameters": [ { "in": "path", - "name": "id", + "name": "songId", "required": true, "schema": { "type": "integer" }, - "description": "Die ID des Songs" + "description": "Die ID des Songs", + "example": 1 } ], "responses": { "200": { - "description": "Song erfolgreich gelöscht" + "description": "Song erfolgreich gelöscht (gibt den gelöschten Song zurück)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Song" + } + } + } }, "400": { - "description": "Ungültige Song-ID" + "description": "Ungültige Song-ID", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Song nicht gefunden" + "description": "Song nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, "/api/songbooks": { "get": { - "summary": "Get all songbooks", + "summary": "Get all songbooks or search songbooks by title", + "tags": [ + "Songbooks" + ], + "parameters": [ + { + "in": "query", + "name": "query", + "required": false, + "schema": { + "type": "string" + }, + "description": "Search term for the songbook title", + "example": "Feiert Jesus" + }, + { + "in": "query", + "name": "q", + "required": false, + "schema": { + "type": "string" + }, + "description": "Alias for `query`", + "example": "Feiert Jesus" + } + ], "responses": { "200": { - "description": "List of songbooks" + "description": "List of songbooks (filtered by title if a query is given)", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SongBook" + } + } + } + } }, "500": { - "description": "Internal Server Error" + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, "post": { "summary": "Creates a new songbook", + "tags": [ + "Songbooks" + ], "requestBody": { "required": true, "content": { @@ -206,7 +513,8 @@ "schema": { "type": "object", "required": [ - "title" + "title", + "language" ], "properties": { "title": { @@ -235,21 +543,7 @@ "example": true }, "songBook": { - "type": "object", - "properties": { - "id": { - "type": "integer", - "example": 1 - }, - "title": { - "type": "string", - "example": "Feiert Jesus 1" - }, - "language": { - "type": "string", - "example": "DE" - } - } + "$ref": "#/components/schemas/SongBook" } } } @@ -257,46 +551,96 @@ } }, "400": { - "description": "Bad Request (missing title)" + "description": "Bad Request (missing title or language)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "409": { - "description": "Conflict (title already exists)" + "description": "Conflict (title already exists)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Internal Server Error" + "description": "Internal Server Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/api/songbooks/{id}": { + "/api/songbooks/{songBookId}": { "get": { - "summary": "Einzelnen Songbook abrufen", + "summary": "Einzelnes Songbook abrufen", "tags": [ "Songbooks" ], "parameters": [ { "in": "path", - "name": "id", + "name": "songBookId", "required": true, "schema": { "type": "integer" }, - "description": "Die ID des Songbooks" + "description": "Die ID des Songbooks", + "example": 1 } ], "responses": { "200": { - "description": "Songbook erfolgreich gefunden" + "description": "Songbook erfolgreich gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBook" + } + } + } }, "400": { - "description": "Ungültige Songbook-ID" + "description": "Ungültige Songbook-ID", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Songbook nicht gefunden" + "description": "Songbook nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, @@ -308,12 +652,13 @@ "parameters": [ { "in": "path", - "name": "id", + "name": "songBookId", "required": true, "schema": { "type": "integer" }, - "description": "Die ID des Songbooks" + "description": "Die ID des Songbooks", + "example": 1 } ], "requestBody": { @@ -321,23 +666,61 @@ "content": { "application/json": { "schema": { - "type": "object" + "type": "object", + "properties": { + "title": { + "type": "string", + "example": "Feiert Jesus 1" + }, + "language": { + "type": "string", + "example": "DE" + } + } } } } }, "responses": { "200": { - "description": "Songbook erfolgreich aktualisiert" + "description": "Songbook erfolgreich aktualisiert", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBook" + } + } + } }, "400": { - "description": "Ungültige Parameter oder Daten" + "description": "Ungültige Parameter oder Daten", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Songbook nicht gefunden" + "description": "Songbook nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, @@ -349,68 +732,64 @@ "parameters": [ { "in": "path", - "name": "id", + "name": "songBookId", "required": true, "schema": { "type": "integer" }, - "description": "Die ID des Songbooks" + "description": "Die ID des Songbooks", + "example": 1 } ], "responses": { "200": { - "description": "Songbook erfolgreich gelöscht" + "description": "Songbook erfolgreich gelöscht (gibt das gelöschte Songbook zurück)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBook" + } + } + } }, "400": { - "description": "Ungültige Songbook-ID" + "description": "Ungültige Songbook-ID", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Songbook nicht gefunden" + "description": "Songbook nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } } }, - "/api/songbooks/{id}/songs": { + "/api/songbooks/{songBookId}/songs": { "get": { "summary": "Einen Song nach Nummer in einem Songbook suchen", "tags": [ - "Songbook" - ], - "parameters": [ - { - "in": "path", - "name": "id", - "required": true, - "schema": { - "type": "integer" - }, - "description": "Die ID des Songbooks" - } - ], - "responses": { - "200": { - "description": "Songbook erfolgreich gefunden" - }, - "400": { - "description": "Ungültige Songbook-ID" - }, - "404": { - "description": "Songbook nicht gefunden" - }, - "500": { - "description": "Serverfehler" - } - } - } - }, - "/api/songbooks/{songBookId}/songs/{songId}": { - "post": { - "summary": "Song zu Liederbuch hinzufügen", - "tags": [ - "Songbook" + "Songbooks" ], "parameters": [ { @@ -420,7 +799,90 @@ "schema": { "type": "integer" }, - "description": "Die ID des Liederbuchs" + "description": "Die ID des Songbooks", + "example": 1 + }, + { + "in": "query", + "name": "number", + "required": true, + "schema": { + "type": "string" + }, + "description": "Die Nummer des Songs im Songbook", + "example": "123" + }, + { + "in": "query", + "name": "n", + "required": false, + "schema": { + "type": "string" + }, + "description": "Alias für `number`", + "example": "123" + } + ], + "responses": { + "200": { + "description": "Song im Songbook erfolgreich gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBookEntry" + } + } + } + }, + "400": { + "description": "Ungültige Songbook-ID oder fehlender number-Parameter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "404": { + "description": "Songbook oder Song nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "500": { + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/songbooks/{songBookId}/songs/{songId}": { + "post": { + "summary": "Song zu Liederbuch hinzufügen", + "tags": [ + "Songbooks" + ], + "parameters": [ + { + "in": "path", + "name": "songBookId", + "required": true, + "schema": { + "type": "integer" + }, + "description": "Die ID des Liederbuchs", + "example": 1 }, { "in": "path", @@ -429,7 +891,8 @@ "schema": { "type": "integer" }, - "description": "Die ID des Songs" + "description": "Die ID des Songs", + "example": 1 } ], "requestBody": { @@ -454,23 +917,51 @@ }, "responses": { "200": { - "description": "Song erfolgreich zugewiesen" + "description": "Song erfolgreich zugewiesen", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBookEntry" + } + } + } }, "400": { - "description": "Ungültige Parameter oder fehlende Songnummer" + "description": "Ungültige Parameter oder fehlende Songnummer", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "409": { - "description": "Songnummer bereits vergeben oder Song existiert bereits im Buch" + "description": "Songnummer bereits vergeben oder Song existiert bereits im Buch", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, "patch": { "summary": "Songnummer eines Songs im Liederbuch aktualisieren", "tags": [ - "Songbook" + "Songbooks" ], "parameters": [ { @@ -480,7 +971,8 @@ "schema": { "type": "integer" }, - "description": "Die ID des Liederbuchs" + "description": "Die ID des Liederbuchs", + "example": 1 }, { "in": "path", @@ -489,7 +981,8 @@ "schema": { "type": "integer" }, - "description": "Die ID des Songs" + "description": "Die ID des Songs", + "example": 1 } ], "requestBody": { @@ -514,26 +1007,61 @@ }, "responses": { "200": { - "description": "Songnummer erfolgreich aktualisiert" + "description": "Songnummer erfolgreich aktualisiert", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBookEntry" + } + } + } }, "400": { - "description": "Ungültige Parameter oder fehlende Daten" + "description": "Ungültige Parameter oder fehlende Daten", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Zuweisung nicht gefunden" + "description": "Zuweisung nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "409": { - "description": "Neue Songnummer bereits vergeben" + "description": "Neue Songnummer bereits vergeben", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } } } }, "delete": { "summary": "Song aus Liederbuch entfernen", "tags": [ - "Songbook" + "Songbooks" ], "parameters": [ { @@ -543,7 +1071,8 @@ "schema": { "type": "integer" }, - "description": "Die ID des Liederbuchs" + "description": "Die ID des Liederbuchs", + "example": 1 }, { "in": "path", @@ -552,26 +1081,92 @@ "schema": { "type": "integer" }, - "description": "Die ID des Songs" + "description": "Die ID des Songs", + "example": 1 } ], "responses": { "200": { - "description": "Song erfolgreich aus dem Liederbuch entfernt" + "description": "Song erfolgreich aus dem Liederbuch entfernt (gibt die entfernte Zuweisung zurück)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SongBookEntry" + } + } + } }, "400": { - "description": "Ungültige Parameter" + "description": "Ungültige Parameter", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "404": { - "description": "Zuweisung nicht gefunden" + "description": "Zuweisung nicht gefunden", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } }, "500": { - "description": "Serverfehler" + "description": "Serverfehler", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/api/docs/api": { + "get": { + "summary": "OpenAPI-Spezifikation abrufen", + "tags": [ + "Docs" + ], + "description": "Gibt die vollständige OpenAPI-JSON-Spezifikation der API zurück.", + "responses": { + "200": { + "description": "Erfolgreich generierte OpenAPI-Spezifikation.", + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "StreamError": { + "type": "object", + "properties": { + "success": { + "type": "boolean", + "example": false + }, + "error": { + "type": "string", + "example": "Fields incomplete!" } } } } }, - "components": {}, "tags": [] } \ No newline at end of file