openapi: 3.0.3
info:
  title: announcementService
  description: Announcing patchnotes for KanzleiApp
  version: 1.0.0

tags:
  - name: Patchnotes
    description: Create, update and read patchnotes

paths:
  /patchnotes:
    get:
      tags: [Patchnotes]
      summary: Returns list of patch notes newer than the caller’s last login
      operationId: listPatchnotes
      parameters:
        - $ref: '#/components/parameters/SinceParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/OffsetParam'
      responses:
        "200":
          description: list of patch notes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/patch_notes'
        "404":
          description: no Patch notes found

    post:
      tags: [Patchnotes]
      summary: Creates new patch notes
      operationId: createPatchnote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patch_notes_input'
      responses:
        "201":
          description: patch note created
          headers:
            Location:
              description: URL of the newly created patch note
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/patch_notes'
        "400":
          description: bad payload

  /patchnotes/{patchID}:
    parameters:
      - in: path
        name: patchID
        required: true
        schema:
          type: string
          format: uuid
        description: ID of the patch note

    get:
      tags: [Patchnotes]
      summary: Returns one patch note
      operationId: getPatchnote
      responses:
        "200":
          description: single patch note
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/patch_notes'
        "404":
          description: no patch note found

    put:
      tags: [Patchnotes]
      summary: Updates one patch note (full replace)
      operationId: updatePatchnote
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/patch_notes_input'
      responses:
        "200":
          description: patch updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/patch_notes'
        "404":
          description: no patch note found

    delete:
      tags: [Patchnotes]
      summary: Deletes one patch note
      operationId: deletePatchnote
      responses:
        "204":
          description: patch successfully deleted
        "404":
          description: patch not found

components:
  parameters:
    SinceParam:
      name: since
      in: query
      description: Only patchnotes newer than this date (YYYY-MM-DD)
      required: false
      schema:
        type: string
        format: date
    LimitParam:
      name: limit
      in: query
      description: Maximum number of items to return
      required: false
      schema:
        type: integer
        default: 20
        minimum: 1
        maximum: 100
    OffsetParam:
      name: offset
      in: query
      description: Pagination offset
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0

  schemas:
    patch_notes:
      type: object
      properties:
        patchID:
          type: string
          format: uuid
        title:
          type: string
        changes:
          type: string
        version:
          type: string
        patch_date:
          type: string
          format: date
      required: [patchID, title, changes, version, patch_date]
      example:
        patchID: 29e80bcc-5981-4a52-99e1-373442dea9b9
        title: Patch note 1
        changes: Fixed export bug
        version: 1.0.0
        patch_date: 2025-01-02

    patch_notes_input:
      description: Schema for POST/PUT (server generates patchID & patch_date if omitted)
      type: object
      properties:
        title:
          type: string
        changes:
          type: string
        version:
          type: string
        patch_date:
          type: string
          format: date
      required: [title, changes, version, patch_date]

  responses:
    Error400:
      description: Invalid request payload
    Error404:
      description: Resource not found