feat(api): Add Swagger UI for v1 endpoints

Serve interactive docs at /api, covering only the current /api/v1/*
endpoints. Deprecated /api/diyanet/* endpoints are left undocumented.

internal/api/openapi.yaml

@@ -0,0 +1,156 @@
+openapi: 3.0.3
+info:
+  title: Prayer Times API
+  version: "1"
+  description: Prayer times and location lookup, backed by Diyanet data.
+externalDocs:
+  description: Source code
+  url: https://git.abdus.dev/abdus/prayertimes-go/
+servers:
+  - url: /
+paths:
+  /api/v1/diyanet/location:
+    get:
+      summary: Search locations
+      description: Search locations by free-text query, or find the nearest location to a coordinate pair.
+      parameters:
+        - name: query
+          in: query
+          description: Free-text location search. Mutually exclusive with latitude/longitude.
+          schema:
+            type: string
+        - name: latitude
+          in: query
+          description: Required together with longitude when query is omitted.
+          schema:
+            type: number
+            format: double
+        - name: longitude
+          in: query
+          description: Required together with latitude when query is omitted.
+          schema:
+            type: number
+            format: double
+      responses:
+        "200":
+          description: Matching locations.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  locations:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/Location"
+        "400":
+          description: Missing both query and coordinates.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /api/v1/diyanet/prayertimes:
+    get:
+      summary: Get prayer times
+      description: Get prayer times by location ID, or by coordinates.
+      parameters:
+        - name: location_id
+          in: query
+          description: Mutually exclusive with latitude/longitude.
+          schema:
+            type: string
+        - name: latitude
+          in: query
+          schema:
+            type: number
+            format: double
+        - name: longitude
+          in: query
+          schema:
+            type: number
+            format: double
+        - name: utc
+          in: query
+          description: Return timestamps in UTC instead of the location's local timezone.
+          schema:
+            type: boolean
+            default: false
+      responses:
+        "200":
+          description: Prayer times for the resolved location.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  location:
+                    $ref: "#/components/schemas/Location"
+                  prayertimes:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/PrayerTimes"
+        "400":
+          description: Missing both location_id and coordinates.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "422":
+          description: Invalid location.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+components:
+  schemas:
+    Location:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        ascii_name:
+          type: string
+        alternate_names:
+          type: string
+        country_code:
+          type: string
+        latitude:
+          type: number
+          format: double
+        longitude:
+          type: number
+          format: double
+        timezone:
+          type: string
+    PrayerTimes:
+      type: object
+      properties:
+        date:
+          type: string
+          format: date
+        date_hijri:
+          type: string
+        fajr:
+          type: string
+          example: "05:47"
+        sunrise:
+          type: string
+        dhuhr:
+          type: string
+        asr:
+          type: string
+        sunset:
+          type: string
+        maghrib:
+          type: string
+        isha:
+          type: string
+    Error:
+      type: object
+      properties:
+        message:
+          type: string