📝 api docs

static/openapi.yaml

@@ -0,0 +1,170 @@
+openapi: 3.0.3
+info:
+  title: Sunday Comics API
+  description: API for accessing webcomic data from the Sunday Comics platform
+  version: 1.0.0
+  contact:
+    url: http://127.0.0.1:3000
+
+servers:
+  - url: http://127.0.0.1:3000
+    description: Development server
+  - url: https://your-production-domain.com
+    description: Production server (update with your actual domain)
+
+paths:
+  /api/comics:
+    get:
+      summary: Get all comics
+      description: Returns a list of all comics with enriched metadata including formatted dates and author notes
+      operationId: getAllComics
+      tags:
+        - Comics
+      responses:
+        '200':
+          description: Successful response with array of comics
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Comic'
+              example:
+                - number: 1
+                  title: "First Comic"
+                  filename: "comic-001.jpg"
+                  mobile_filename: "comic-001-mobile.jpg"
+                  date: "2025-01-01"
+                  alt_text: "The very first comic"
+                  author_note: "This is where your comic journey begins!"
+                  full_width: true
+                  plain: true
+                  formatted_date: "Wednesday, January 1, 2025"
+                  author_note_is_html: false
+                - number: 2
+                  filename: "comic-002.jpg"
+                  date: "2025-01-08"
+                  alt_text: "The second comic"
+                  full_width: true
+                  plain: true
+                  formatted_date: "Wednesday, January 8, 2025"
+                  author_note_is_html: false
+
+  /api/comics/{comic_id}:
+    get:
+      summary: Get a specific comic
+      description: Returns a single comic by its number/ID with enriched metadata
+      operationId: getComicById
+      tags:
+        - Comics
+      parameters:
+        - name: comic_id
+          in: path
+          description: Comic number/ID
+          required: true
+          schema:
+            type: integer
+            minimum: 1
+          example: 1
+      responses:
+        '200':
+          description: Successful response with comic data
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Comic'
+              example:
+                number: 1
+                title: "First Comic"
+                filename: "comic-001.jpg"
+                mobile_filename: "comic-001-mobile.jpg"
+                date: "2025-01-01"
+                alt_text: "The very first comic"
+                author_note: "This is where your comic journey begins!"
+                full_width: true
+                plain: true
+                formatted_date: "Wednesday, January 1, 2025"
+                author_note_is_html: false
+        '404':
+          description: Comic not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              example:
+                error: "Comic not found"
+
+components:
+  schemas:
+    Comic:
+      type: object
+      required:
+        - number
+        - filename
+        - date
+        - alt_text
+        - full_width
+        - plain
+        - formatted_date
+        - author_note_is_html
+      properties:
+        number:
+          type: integer
+          description: Sequential comic number (unique identifier)
+          minimum: 1
+          example: 1
+        title:
+          type: string
+          description: Comic title (optional, defaults to "#X" if not provided)
+          example: "First Comic"
+        filename:
+          type: string
+          description: Image filename in static/images/comics/
+          example: "comic-001.jpg"
+        mobile_filename:
+          type: string
+          description: Optional mobile version of the comic image
+          example: "comic-001-mobile.jpg"
+        date:
+          type: string
+          format: date
+          description: Publication date in YYYY-MM-DD format
+          example: "2025-01-01"
+        alt_text:
+          type: string
+          description: Accessibility text for the comic image
+          example: "The very first comic"
+        author_note:
+          type: string
+          description: Author's note about the comic (plain text or HTML from markdown)
+          example: "This is where your comic journey begins!"
+        full_width:
+          type: boolean
+          description: Whether the comic should display in full-width mode (computed from global default and per-comic override)
+          example: true
+        plain:
+          type: boolean
+          description: Whether the comic should display in plain mode without header/borders (computed from global default and per-comic override)
+          example: true
+        formatted_date:
+          type: string
+          description: Human-readable formatted date (computed field)
+          example: "Wednesday, January 1, 2025"
+        author_note_is_html:
+          type: boolean
+          description: Indicates whether author_note contains HTML (from markdown) or plain text (computed field)
+          example: false
+
+    Error:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: string
+          description: Error message
+          example: "Comic not found"
+
+tags:
+  - name: Comics
+    description: Operations for accessing comic data