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