announcement_service_spec.yaml updated, patchnotes_controller.py updated accordingly to changes

announcement_service_spec.yaml

@@ -3,144 +3,183 @@ info:
   title: announcementService
   description: Announcing patchnotes for KanzleiApp
   version: 1.0.0
+
+tags:
+  - name: Patchnotes
+    description: Create, update and read patchnotes
+
 paths:
   /patchnotes:
-    post:
-      tags:
-        - Patchnotes
-      description: creates new Patch notes
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/patch_notes'
-      responses:
-        "200":
-          description: game created
-          content:
-            application/json:
-              schema:
-                  $ref: '#/components/schemas/patch_notes'
-        "400":
-          description: bad payload
     get:
-      description: returns list of all Patch notes
+      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'
-          description: returns list of all unseen Patch notes from the user
         "404":
           description: no Patch notes found
-      tags:
+
-        - Patchnotes
+    post:
-      x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
+      tags: [Patchnotes]
-  /patchnotes/{patchID}:
+      summary: Creates new patch notes
-    put:
+      operationId: createPatchnote
-      tags:
-        - Patchnotes
-      description: Updates one Patch
-      parameters:
-        - in: path
-          name: patchID
-          required: true
-          schema:
-            format: uuid
-            type: string
       requestBody:
+        required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/patch_notes'
+              $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
-        "404":
-          description: no patch found
-    delete:
-      tags:
-        - Patchnotes
-      description: deletes one Patch note
-      parameters:
-        - in: path
-          name: patchID
-          required: true
-          schema:
-            format: uuid
-            type: string
-          style: simple
-      responses:
-        "200":
-          description: patch successfully deleted
-        "404":
-          description: patch not found
-  /patchnotes/{date}:
-    get:
-      description: returns list of all unseen Patch notes from the user
-      parameters:
-        - explode: false
-          in: path
-          name: date
-          required: true
-          schema:
-            format: date
-            type: string
-          style: simple
-          example: 2025-01-02
-      responses:
-        "200":
           content:
             application/json:
               schema:
-                type: array
+                $ref: '#/components/schemas/patch_notes'
-                items:
-                  $ref: '#/components/schemas/patch_notes'
-          description: returns list of all unseen Patch notes from the user
         "404":
-          description: no Patch notes found
+          description: no patch note found
-      tags:
+
-        - Patchnotes
+    delete:
-      x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
+      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: changes
+        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:
-        patchID:
-          format: uuid
-          title: patchID
-          type: string
         title:
           type: string
-          title: title
         changes:
           type: string
-          title: changes
         version:
           type: string
-          title: version
         patch_date:
-          title: patch_date
           type: string
-      required:
-        - "title"
-        - "changes"
-        - "patch_date"
-        - "version"
-    user:
-      example:
-        lastSeenDate: 2025-01-02
-      properties:
-        lastSeenDate:
           format: date
-          title: lastNoteChecked
+      required: [title, changes, version, patch_date]
-          type: string
+
+  responses:
+    Error400:
+      description: Invalid request payload
+    Error404:
+      description: Resource not found

gen/.openapi-generator-ignore

@@ -21,8 +21,8 @@
 #docs/*.md
 # Then explicitly reverse the ignore rule for a single file:
 #!docs/README.md
+openapi_server/encoder.py
 openapi_server/controllers/patchnotes_controller.py
 openapi_server/__main__.py
-openapi_server/encoder.py
 openapi_server/models/base_model.py
 requirements.txt

gen/.openapi-generator/FILES

@@ -5,16 +5,18 @@ Dockerfile
 README.md
 git_push.sh
 openapi_server/__init__.py
+openapi_server/__main__.py
 openapi_server/controllers/__init__.py
+openapi_server/controllers/patchnotes_controller.py
 openapi_server/controllers/security_controller.py
 openapi_server/models/__init__.py
+openapi_server/models/base_model.py
 openapi_server/models/patch_notes.py
-openapi_server/models/user.py
+openapi_server/models/patch_notes_input.py
 openapi_server/openapi/openapi.yaml
 openapi_server/test/__init__.py
 openapi_server/typing_utils.py
 openapi_server/util.py
-requirements.txt
 setup.py
 test-requirements.txt
 tox.ini

gen/openapi_server/controllers/patchnotes_controller.py

@@ -1,3 +1,11 @@
+import connexion
+from typing import Dict
+from typing import Tuple
+from typing import Union
+
+from openapi_server.models.patch_notes import PatchNotes  # noqa: E501
+from openapi_server.models.patch_notes_input import PatchNotesInput  # noqa: E501
+from openapi_server import util
 import logging
 import uuid
 from datetime import datetime
@@ -8,47 +16,55 @@ from flask import Response
 from __main__ import collection
 
 from openapi_server.__main__ import collection
-from openapi_server.models.patch_notes import PatchNotes  # noqa: E501
+from openapi_server.models.patch_notes import PatchNotes
 
 
-def patchnotes_date_get(date):  # noqa: E501
+def create_patchnote(body):  # noqa: E501
-    """patchnotes_date_get
+    """Creates new patch notes
 
-    returns list of all unseen Patch notes from the user # noqa: E501
+     # noqa: E501
 
-    :param date:
+    :param body:
-    :type date: str
+    :param patch_notes_input:
+    :type patch_notes_input: dict | bytes
 
-    :rtype: Union[List[PatchNotes], Tuple[List[PatchNotes], int], Tuple[List[PatchNotes], int, Dict[str, str]]
+    :rtype: Union[PatchNotes, Tuple[PatchNotes, int], Tuple[PatchNotes, int, Dict[str, str]]
     """
+    patch_notes_input = body
+    if body is None:
+        return Response('error: No patch notes provided', status=400)
+    pn = PatchNotes.from_dict(body)
     try:
-        datetime.strptime(date, '%Y-%m-%d') # 2025-01-0
+        date_obj = datetime.strptime(pn.patch_date, '%Y-%m-%d').date()
+        date_str = date_obj.strftime('%Y-%m-%d')
     except ValueError as e:
         raise ProblemException(
             title="Bad Request",
             detail="The date is invalid. Needs to be in this Format YYYY-MM-DD",
             status=400,
         )
-    query = {
+
-        'patch_date': {'$gte': date}
+    patch_note = {
+        'patchID': str(uuid.uuid4()),
+        'title': pn.title,
+        'changes': pn.changes,
+        'version': pn.version,
+        'patch_date': date_str
     }
-    results = []
+
-    for entry in collection.find(query):
+    collection.insert_one(patch_note)
-        patch_note = PatchNotes.from_dict(entry)
+    patch_note_obj = PatchNotes.from_dict(patch_note)
-        results.append(patch_note.to_dict())
+    patch_note = patch_note_obj.to_dict()
-    return Response(
+    return Response(json_util.dumps(patch_note), mimetype='application/json',
-        json_util.dumps(results),
+                    status=200)
-        mimetype='application/json',
-        status=200,
-    )
 
 
-def patchnotes_patch_iddelete(patch_id):  # noqa: E501
+def delete_patchnote(patch_id):  # noqa: E501
-    """patchnotes_patch_iddelete
+    """Deletes one patch note
 
-    deletes one Patch note # noqa: E501
+     # noqa: E501
 
-    :param patch_id:
+    :param patch_id: ID of the patch note
     :type patch_id: str
     :type patch_id: str
 
@@ -62,23 +78,85 @@ def patchnotes_patch_iddelete(patch_id):  # noqa: E501
             status=404,
         )
     return Response(
-    "Document was deleted",
+        "Document was deleted",
         mimetype='application/json',
         status=200,
     )
 
 
-def patchnotes_patch_idput(patch_id, body):  # noqa: E501
+def get_patchnote(patch_id):  # noqa: E501
-    """patchnotes_patch_idput
+    """Returns one patch note
 
-    Updates one Patch # noqa: E501
+     # noqa: E501
+
+    :param patch_id: ID of the patch note
+    :type patch_id: str
+    :type patch_id: str
+
+    :rtype: Union[PatchNotes, Tuple[PatchNotes, int], Tuple[PatchNotes, int, Dict[str, str]]
+    """
+    pn = collection.find_one({'patchID': patch_id})
+    if pn is None:
+        raise ProblemException(
+            title="Not found",
+            detail="No document has been found",
+            status=404,
+        )
+    return Response(
+        json_util.dumps(pn),
+        mimetype='application/json',
+        status=200,
+    )
+
+def list_patchnotes(since=None, limit=None, offset=None):  # noqa: E501
+    """Returns list of patch notes newer than the caller’s last login
+
+     # noqa: E501
+
+    :param since: Only patchnotes newer than this date (YYYY-MM-DD)
+    :type since: str
+    :param limit: Maximum number of items to return
+    :type limit: int
+    :param offset: Pagination offset
+    :type offset: int
+
+    :rtype: Union[List[PatchNotes], Tuple[List[PatchNotes], int], Tuple[List[PatchNotes], int, Dict[str, str]]
+    """
+    try:
+        datetime.strptime(since, '%Y-%m-%d')  # 2025-01-0
+    except ValueError as e:
+        raise ProblemException(
+            title="Bad Request",
+            detail="The date is invalid. Needs to be in this Format YYYY-MM-DD",
+            status=400,
+        )
+    query = {
+        'patch_date': {'$gte': since}
+    }
+    results = []
+    for entry in collection.find(query):
+        patch_note = PatchNotes.from_dict(entry)
+        results.append(patch_note.to_dict())
+    return Response(
+        json_util.dumps(results),
+        mimetype='application/json',
+        status=200,
+    )
+
+
+def update_patchnote(patch_id, body):  # noqa: E501
+    """Updates one patch note (full replace)
+
+     # noqa: E501
 
     :param body:
-    :param patch_id:
+    :param patch_id: ID of the patch note
     :type patch_id: str
     :type patch_id: str
+    :param patch_notes_input: 
+    :type patch_notes_input: dict | bytes
 
-    :rtype: Union[None, Tuple[None, int], Tuple[None, int, Dict[str, str]]
+    :rtype: Union[PatchNotes, Tuple[PatchNotes, int], Tuple[PatchNotes, int, Dict[str, str]]
     """
     pn = PatchNotes.from_dict(body)
     try:
@@ -93,10 +171,10 @@ def patchnotes_patch_idput(patch_id, body):  # noqa: E501
     query_filter = {'patchID': patch_id}
     updated_post = {'$set':
         {
-        'title': pn.title,
+            'title': pn.title,
-        'changes': pn.changes,
+            'changes': pn.changes,
-        'version': pn.version,
+            'version': pn.version,
-        'date': date_str
+            'date': date_str
         }
     }
     result = collection.update_one(query_filter, updated_post)
@@ -107,108 +185,3 @@ def patchnotes_patch_idput(patch_id, body):  # noqa: E501
             status=404,
         )
     return Response("Document was updated", status=200, mimetype='application/json')
-
-
-def patchnotes_post(body):
-    """patchnotes_post
-
-    creates new Patch notes # noqa: E501
-
-    :param body:
-    :param patch_notes:
-    :type patch_notes: dict | bytes
-
-    :rtype: Union[List[PatchNotes], Tuple[List[PatchNotes], int], Tuple[List[PatchNotes], int, Dict[str, str]]
-    """
-    if body is None:
-        return Response('error: No patch notes provided', status=400)
-    pn = PatchNotes.from_dict(body)
-    try:
-        date_obj = datetime.strptime(pn.patch_date, '%Y-%m-%d').date()
-        date_str = date_obj.strftime('%Y-%m-%d')
-    except ValueError as e:
-        raise ProblemException(
-            title="Bad Request",
-            detail="The date is invalid. Needs to be in this Format YYYY-MM-DD",
-            status=400,
-        )
-
-    patch_note = {
-        'patchID': str(uuid.uuid4()),
-        'title': pn.title,
-        'changes': pn.changes,
-        'version': pn.version,
-        'patch_date': date_str
-    }
-
-    collection.insert_one(patch_note)
-    patch_note_obj = PatchNotes.from_dict(patch_note)
-    patch_note = patch_note_obj.to_dict()
-    return Response(json_util.dumps(patch_note), mimetype='application/json',
-                    status=200)
-
-def patchnotes_post(body):
-    """patchnotes_post
-
-    creates new Patch notes # noqa: E501
-
-    :param body:
-    :param patch_notes:
-    :type patch_notes: dict | bytes
-
-    :rtype: Union[List[PatchNotes], Tuple[List[PatchNotes], int], Tuple[List[PatchNotes], int, Dict[str, str]]
-    """
-    if body is None:
-        return Response('error: No patch notes provided', status=400)
-    pn = PatchNotes.from_dict(body)
-    try:
-        date_obj = datetime.strptime(pn.patch_date, '%Y-%m-%d').date()
-        date_str = date_obj.strftime('%Y-%m-%d')
-    except ValueError as e:
-        raise ProblemException(
-            title="Bad Request",
-            detail="The date is invalid. Needs to be in this Format YYYY-MM-DD",
-            status=400,
-        )
-
-    patch_note = {
-        'patchID': str(uuid.uuid4()),
-        'title': pn.title,
-        'changes': pn.changes,
-        'version': pn.version,
-        'patch_date': date_str
-    }
-
-    collection.insert_one(patch_note)
-    patch_note_obj = PatchNotes.from_dict(patch_note)
-    patch_note = patch_note_obj.to_dict()
-    return Response(json_util.dumps(patch_note), mimetype='application/json',
-                    status=200)
-
-
-def patchnotes_get():  # noqa: E501
-    """patchnotes_get
-
-    returns list of all Patch notes # noqa: E501
-
-
-    :rtype: Union[List[PatchNotes], Tuple[List[PatchNotes], int], Tuple[List[PatchNotes], int, Dict[str, str]]
-    """
-    results = []
-    for entry in collection.find({}):
-        patch_note = PatchNotes.from_dict(entry)
-        results.append(patch_note.to_dict())
-    return Response(
-        json_util.dumps(results),
-        mimetype='application/json',
-        status=200,
-    )
-
-def cors_options_handler():
-    from flask import make_response
-    response = make_response('')
-    response.headers['Access-Control-Allow-Origin'] = '*'
-    response.headers['Access-Control-Allow-Methods'] = 'GET, POST, PUT, DELETE, OPTIONS'
-    response.headers['Access-Control-Allow-Headers'] = 'Content-Type, Authorization'
-    return response
-

gen/openapi_server/models/__init__.py

@@ -1,4 +1,4 @@
 # flake8: noqa
 # import models into model package
 from openapi_server.models.patch_notes import PatchNotes
-from openapi_server.models.user import User
+from openapi_server.models.patch_notes_input import PatchNotesInput

gen/openapi_server/models/base_model.py

@@ -1,7 +1,6 @@
 import pprint
 
 import typing
-from datetime import datetime
 
 from openapi_server import util
 
@@ -29,26 +28,23 @@ class Model:
         """
         result = {}
 
-        for attr, _ in self.openapi_types.items():
+        for attr in self.openapi_types:
             value = getattr(self, attr)
-            dict_attr = self.attribute_map[attr]
             if isinstance(value, list):
-                result[dict_attr] = list(map(
+                result[attr] = list(map(
                     lambda x: x.to_dict() if hasattr(x, "to_dict") else x,
                     value
                 ))
             elif hasattr(value, "to_dict"):
-                result[dict_attr] = value.to_dict()
+                result[attr] = value.to_dict()
             elif isinstance(value, dict):
-                result[dict_attr] = dict(map(
+                result[attr] = dict(map(
                     lambda item: (item[0], item[1].to_dict())
                     if hasattr(item[1], "to_dict") else item,
                     value.items()
                 ))
-            elif isinstance(value, datetime):
-                result[dict_attr] = value.isoformat()
             else:
-                result[dict_attr] = value
+                result[attr] = value
 
         return result
 

gen/openapi_server/models/patch_notes.py

@@ -24,14 +24,14 @@ class PatchNotes(Model):
         :param version: The version of this PatchNotes.  # noqa: E501
         :type version: str
         :param patch_date: The patch_date of this PatchNotes.  # noqa: E501
-        :type patch_date: str
+        :type patch_date: date
         """
         self.openapi_types = {
             'patch_id': str,
             'title': str,
             'changes': str,
             'version': str,
-            'patch_date': str
+            'patch_date': date
         }
 
         self.attribute_map = {
@@ -77,6 +77,8 @@ class PatchNotes(Model):
         :param patch_id: The patch_id of this PatchNotes.
         :type patch_id: str
         """
+        if patch_id is None:
+            raise ValueError("Invalid value for `patch_id`, must not be `None`")  # noqa: E501
 
         self._patch_id = patch_id
 
@@ -150,22 +152,22 @@ class PatchNotes(Model):
         self._version = version
 
     @property
-    def patch_date(self) -> str:
+    def patch_date(self) -> date:
         """Gets the patch_date of this PatchNotes.
 
 
         :return: The patch_date of this PatchNotes.
-        :rtype: str
+        :rtype: date
         """
         return self._patch_date
 
     @patch_date.setter
-    def patch_date(self, patch_date: str):
+    def patch_date(self, patch_date: date):
         """Sets the patch_date of this PatchNotes.
 
 
         :param patch_date: The patch_date of this PatchNotes.
-        :type patch_date: str
+        :type patch_date: date
         """
         if patch_date is None:
             raise ValueError("Invalid value for `patch_date`, must not be `None`")  # noqa: E501

gen/openapi_server/models/patch_notes_input.py

@@ -0,0 +1,147 @@
+from datetime import date, datetime  # noqa: F401
+
+from typing import List, Dict  # noqa: F401
+
+from openapi_server.models.base_model import Model
+from openapi_server import util
+
+
+class PatchNotesInput(Model):
+    """NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+
+    Do not edit the class manually.
+    """
+
+    def __init__(self, title=None, changes=None, version=None, patch_date=None):  # noqa: E501
+        """PatchNotesInput - a model defined in OpenAPI
+
+        :param title: The title of this PatchNotesInput.  # noqa: E501
+        :type title: str
+        :param changes: The changes of this PatchNotesInput.  # noqa: E501
+        :type changes: str
+        :param version: The version of this PatchNotesInput.  # noqa: E501
+        :type version: str
+        :param patch_date: The patch_date of this PatchNotesInput.  # noqa: E501
+        :type patch_date: date
+        """
+        self.openapi_types = {
+            'title': str,
+            'changes': str,
+            'version': str,
+            'patch_date': date
+        }
+
+        self.attribute_map = {
+            'title': 'title',
+            'changes': 'changes',
+            'version': 'version',
+            'patch_date': 'patch_date'
+        }
+
+        self._title = title
+        self._changes = changes
+        self._version = version
+        self._patch_date = patch_date
+
+    @classmethod
+    def from_dict(cls, dikt) -> 'PatchNotesInput':
+        """Returns the dict as a model
+
+        :param dikt: A dict.
+        :type: dict
+        :return: The patch_notes_input of this PatchNotesInput.  # noqa: E501
+        :rtype: PatchNotesInput
+        """
+        return util.deserialize_model(dikt, cls)
+
+    @property
+    def title(self) -> str:
+        """Gets the title of this PatchNotesInput.
+
+
+        :return: The title of this PatchNotesInput.
+        :rtype: str
+        """
+        return self._title
+
+    @title.setter
+    def title(self, title: str):
+        """Sets the title of this PatchNotesInput.
+
+
+        :param title: The title of this PatchNotesInput.
+        :type title: str
+        """
+        if title is None:
+            raise ValueError("Invalid value for `title`, must not be `None`")  # noqa: E501
+
+        self._title = title
+
+    @property
+    def changes(self) -> str:
+        """Gets the changes of this PatchNotesInput.
+
+
+        :return: The changes of this PatchNotesInput.
+        :rtype: str
+        """
+        return self._changes
+
+    @changes.setter
+    def changes(self, changes: str):
+        """Sets the changes of this PatchNotesInput.
+
+
+        :param changes: The changes of this PatchNotesInput.
+        :type changes: str
+        """
+        if changes is None:
+            raise ValueError("Invalid value for `changes`, must not be `None`")  # noqa: E501
+
+        self._changes = changes
+
+    @property
+    def version(self) -> str:
+        """Gets the version of this PatchNotesInput.
+
+
+        :return: The version of this PatchNotesInput.
+        :rtype: str
+        """
+        return self._version
+
+    @version.setter
+    def version(self, version: str):
+        """Sets the version of this PatchNotesInput.
+
+
+        :param version: The version of this PatchNotesInput.
+        :type version: str
+        """
+        if version is None:
+            raise ValueError("Invalid value for `version`, must not be `None`")  # noqa: E501
+
+        self._version = version
+
+    @property
+    def patch_date(self) -> date:
+        """Gets the patch_date of this PatchNotesInput.
+
+
+        :return: The patch_date of this PatchNotesInput.
+        :rtype: date
+        """
+        return self._patch_date
+
+    @patch_date.setter
+    def patch_date(self, patch_date: date):
+        """Sets the patch_date of this PatchNotesInput.
+
+
+        :param patch_date: The patch_date of this PatchNotesInput.
+        :type patch_date: date
+        """
+        if patch_date is None:
+            raise ValueError("Invalid value for `patch_date`, must not be `None`")  # noqa: E501
+
+        self._patch_date = patch_date

gen/openapi_server/openapi/openapi.yaml

@@ -5,11 +5,44 @@ info:
   version: 1.0.0
 servers:
 - url: /
+tags:
+- description: "Create, update and read patchnotes"
+  name: Patchnotes
 paths:
   /patchnotes:
     get:
-      description: returns list of all Patch notes
+      operationId: list_patchnotes
-      operationId: patchnotes_get
+      parameters:
+      - description: Only patchnotes newer than this date (YYYY-MM-DD)
+        explode: true
+        in: query
+        name: since
+        required: false
+        schema:
+          format: date
+          type: string
+        style: form
+      - description: Maximum number of items to return
+        explode: true
+        in: query
+        name: limit
+        required: false
+        schema:
+          default: 20
+          maximum: 100
+          minimum: 1
+          type: integer
+        style: form
+      - description: Pagination offset
+        explode: true
+        in: query
+        name: offset
+        required: false
+        schema:
+          default: 0
+          minimum: 0
+          type: integer
+        style: form
       responses:
         "200":
           content:
@@ -18,86 +51,93 @@ paths:
                 items:
                   $ref: '#/components/schemas/patch_notes'
                 type: array
-          description: returns list of all unseen Patch notes from the user
+          description: list of patch notes
         "404":
           description: no Patch notes found
+      summary: Returns list of patch notes newer than the caller’s last login
       tags:
       - Patchnotes
       x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
     post:
-      description: creates new Patch notes
+      operationId: create_patchnote
-      operationId: patchnotes_post
       requestBody:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/patch_notes'
+              $ref: '#/components/schemas/patch_notes_input'
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/patch_notes'
+          description: patch note created
+          headers:
+            Location:
+              description: URL of the newly created patch note
+              explode: false
+              schema:
+                type: string
+              style: simple
+        "400":
+          description: bad payload
+      summary: Creates new patch notes
+      tags:
+      - Patchnotes
+      x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
+  /patchnotes/{patchID}:
+    delete:
+      operationId: delete_patchnote
+      parameters:
+      - description: ID of the patch note
+        explode: false
+        in: path
+        name: patchID
+        required: true
+        schema:
+          format: uuid
+          type: string
+        style: simple
+      responses:
+        "204":
+          description: patch successfully deleted
+        "404":
+          description: patch not found
+      summary: Deletes one patch note
+      tags:
+      - Patchnotes
+      x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
+    get:
+      operationId: get_patchnote
+      parameters:
+      - description: ID of the patch note
+        explode: false
+        in: path
+        name: patchID
+        required: true
+        schema:
+          format: uuid
+          type: string
+        style: simple
       responses:
         "200":
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/patch_notes'
-          description: game created
+          description: single patch note
-        "400":
-          description: bad payload
-      tags:
-      - Patchnotes
-      x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
-  /patchnotes/{date}:
-    get:
-      description: returns list of all unseen Patch notes from the user
-      operationId: patchnotes_date_get
-      parameters:
-      - example: 2025-01-02
-        explode: false
-        in: path
-        name: date
-        required: true
-        schema:
-          format: date
-          type: string
-        style: simple
-      responses:
-        "200":
-          content:
-            application/json:
-              schema:
-                items:
-                  $ref: '#/components/schemas/patch_notes'
-                type: array
-          description: returns list of all unseen Patch notes from the user
         "404":
-          description: no Patch notes found
+          description: no patch note found
-      tags:
+      summary: Returns one patch note
-      - Patchnotes
-      x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
-  /patchnotes/{patchID}:
-    delete:
-      description: deletes one Patch note
-      operationId: patchnotes_patch_iddelete
-      parameters:
-      - explode: false
-        in: path
-        name: patchID
-        required: true
-        schema:
-          format: uuid
-          type: string
-        style: simple
-      responses:
-        "200":
-          description: patch successfully deleted
-        "404":
-          description: patch not found
       tags:
       - Patchnotes
       x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
     put:
-      description: Updates one Patch
+      operationId: update_patchnote
-      operationId: patchnotes_patch_idput
       parameters:
-      - explode: false
+      - description: ID of the patch note
+        explode: false
         in: path
         name: patchID
         required: true
@@ -109,29 +149,93 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/patch_notes'
+              $ref: '#/components/schemas/patch_notes_input'
+        required: true
       responses:
         "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/patch_notes'
           description: patch updated
         "404":
-          description: no patch found
+          description: no patch note found
+      summary: Updates one patch note (full replace)
       tags:
       - Patchnotes
       x-openapi-router-controller: openapi_server.controllers.patchnotes_controller
 components:
+  parameters:
+    SinceParam:
+      description: Only patchnotes newer than this date (YYYY-MM-DD)
+      explode: true
+      in: query
+      name: since
+      required: false
+      schema:
+        format: date
+        type: string
+      style: form
+    LimitParam:
+      description: Maximum number of items to return
+      explode: true
+      in: query
+      name: limit
+      required: false
+      schema:
+        default: 20
+        maximum: 100
+        minimum: 1
+        type: integer
+      style: form
+    OffsetParam:
+      description: Pagination offset
+      explode: true
+      in: query
+      name: offset
+      required: false
+      schema:
+        default: 0
+        minimum: 0
+        type: integer
+      style: form
+  responses:
+    Error400:
+      description: Invalid request payload
+    Error404:
+      description: Resource not found
   schemas:
     patch_notes:
       example:
         patchID: 29e80bcc-5981-4a52-99e1-373442dea9b9
         title: Patch note 1
-        changes: changes
+        changes: Fixed export bug
         version: 1.0.0
         patch_date: 2025-01-02
       properties:
         patchID:
           format: uuid
-          title: patchID
           type: string
+        title:
+          type: string
+        changes:
+          type: string
+        version:
+          type: string
+        patch_date:
+          format: date
+          type: string
+      required:
+      - changes
+      - patchID
+      - patch_date
+      - title
+      - version
+      title: patch_notes
+      type: object
+    patch_notes_input:
+      description: Schema for POST/PUT (server generates patchID & patch_date if omitted)
+      properties:
         title:
           title: title
           type: string
@@ -142,6 +246,7 @@ components:
           title: version
           type: string
         patch_date:
+          format: date
           title: patch_date
           type: string
       required:
@@ -149,12 +254,5 @@ components:
       - patch_date
       - title
       - version
-      title: patch_notes
+      title: patch_notes_input
-    user:
+      type: object
-      example:
-        lastSeenDate: 2025-01-02
-      properties:
-        lastSeenDate:
-          format: date
-          title: lastNoteChecked
-          type: string