Add aiohttp-swagger3 openapi.json creation

Author: gbtami

docs/api/export_user_pgn.yaml

@@ -0,0 +1,109 @@
+summary: Export user games as PGN
+description: >
+  Streams the authenticated user's games in PGN format.
+
+  The requester must be logged in as the same user as `profileId`, unless the
+  requester is an administrator. The response is streamed as PGN text and may
+  contain multiple games.
+
+tags:
+  - Games
+
+operationId: exportUserGamesPgn
+
+parameters:
+  - name: profileId
+    in: path
+    required: true
+    description: Username/profile id whose games should be exported.
+    schema:
+      type: string
+    example: gbtami
+
+  - name: max
+    in: query
+    required: false
+    description: >
+      Maximum number of latest games to export. Must be a positive integer.
+      If omitted, all matching games are exported.
+    schema:
+      type: integer
+      minimum: 1
+    example: 100
+
+  - name: filter
+    in: query
+    required: false
+    description: >
+      Optional game filter. If omitted, all games are exported.
+    schema:
+      type: string
+      enum:
+        - all
+        - win
+        - loss
+        - rated
+        - playing
+        - import
+        - me
+        - perf
+      default: all
+    example: rated
+
+  - name: variant
+    in: query
+    required: false
+    description: >
+      Variant filter, mainly useful together with filter=perf.
+      Use pychess variant names, for example chess, crazyhouse, shogi, xiangqi,
+      capablanca, or chess960-style names where supported.
+    schema:
+      type: string
+    example: chess
+
+  - name: x
+    in: query
+    required: false
+    description: >
+      Engine level filter used by some loss/performance views.
+      This is passed through to the server's existing game filtering logic.
+    schema:
+      type: integer
+      minimum: 1
+    example: 3
+
+responses:
+  "200":
+    description: >
+      PGN export stream. The body may be empty if the profile does not exist,
+      the requester is anonymous, or no games match the filters.
+    content:
+      text/pgn:
+        schema:
+          type: string
+          description: One or more PGN games concatenated into a text stream.
+        example: |
+          [Event "Rated chess game"]
+          [Site "https://www.pychess.org"]
+          [White "Alice"]
+          [Black "Bob"]
+          [Result "1-0"]
+
+          1. e4 e5 2. Nf3 Nc6 1-0
+
+  "400":
+    description: Invalid query parameter, for example max is not a positive integer.
+    content:
+      text/plain:
+        schema:
+          type: string
+        example: Query parameter 'max' must be a positive integer.
+
+  "403":
+    description: The authenticated user is not allowed to export this user's games.
+    content:
+      text/plain:
+        schema:
+          type: string
+        example: Users can only export their own games.
+

pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "aiohttp-jinja2==1.6",
     "aiohttp-session==2.12.1",
     "aiohttp-sse==2.2.0",
+    "aiohttp-swagger3==0.10.0",
     "brotli==1.2.0",
     "cryptography==48.0.0",
     "discord-py==2.7.1",

server/game_api.py

@@ -10,6 +10,7 @@
 from aiohttp_sse import sse_response
 import pymongo
 from pymongo.errors import BulkWriteError
+from aiohttp_swagger3 import swagger_doc
 
 from compress import C2R, decode_move_standard
 from const import DARK_FEN, STARTED, MATE, INVALIDMOVE, VARIANTEND, CLAIM, SSE_GET_TIMEOUT, SWISS
@@ -651,6 +652,7 @@ async def get_games(request: web.Request) -> web.StreamResponse:
     )
 
 
+@swagger_doc("docs/api/export_user_pgn.yaml")
 async def export(request: web.Request) -> web.StreamResponse:
     app_state = get_app_state(request.app)
     profileId = request.match_info.get("profileId")

server/server.py

@@ -18,6 +18,7 @@
 import jinja2
 
 from pymongo import AsyncMongoClient
+from aiohttp_swagger3 import SwaggerDocs, SwaggerInfo
 
 from db_wrapper import AsyncDBWrapper
 from middlewares import (
@@ -58,7 +59,15 @@ def make_app(
     simple_cookie_storage: bool = False,
     anon_as_test_users: bool = False,
 ) -> Application:
+
     app = web.Application()
+
+    swagger = SwaggerDocs(
+        app,
+        validate=False,
+        info=SwaggerInfo(title="Pychess API", version="1.0.0"),
+    )
+
     app.middlewares.append(redirect_to_https)
     app[request_protection_state_key] = RequestProtectionState()
     app.middlewares.append(request_protection_middleware)
@@ -104,11 +113,27 @@ def make_app(
     app.on_shutdown.append(shutdown)
     app.on_cleanup.append(close_mongodb_client)
 
+    async def openapi_json(request):
+        return web.json_response(swagger.spec)
+
+    app.router.add_get("/openapi.json", openapi_json)
+
     # Setup routes.
     for route in get_routes:
-        app.router.add_get(route[0], route[1], allow_head=False)
+        path, handler = route
+        if path == "/api/games/user/{profileId}/pgn":
+            swagger.add_get(
+                path,
+                handler,
+                allow_head=False,
+            )
+        else:
+            app.router.add_get(path, handler, allow_head=False)
+
     for route in post_routes:
-        app.router.add_post(route[0], route[1])
+        path, handler = route
+        app.router.add_post(path, handler)
+
     app.router.add_static("/static", "static", append_version=True)
     app.middlewares.append(handle_404)