From 322a273dafa5bed16d12a4d8ddea51a55a7cf5e7 Mon Sep 17 00:00:00 2001
From: emmixeryng <emmixeryng@users.noreply.github.com>
Date: Tue, 28 Jul 2026 21:28:58 +0100
Subject: [PATCH] docs(openapi): add OpenAPI examples for
 /api/admin/users/{address}/impersonate [b#046]

- Add POST /api/admin/users/{address}/impersonate endpoint to OpenAPI spec
- Include example request/response bodies for 200, 400, and 403 responses
---
 openapi.yaml     | 71 ++++++++++++++++++++++++++++++++++++++++++++++++
 src/openapi.yaml | 71 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 142 insertions(+)

diff --git a/openapi.yaml b/openapi.yaml
index 62e9d7ae..41dbc831 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -3474,6 +3474,77 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorBody'
+  /api/admin/users/{address}/impersonate:
+    post:
+      operationId: impersonateUser
+      tags:
+        - Admin
+      summary: Generate an impersonation JWT for a user (admin only)
+      description: >-
+        Admin-only endpoint that creates an audit-logged JWT allowing the
+        caller to act as the target user. The generated token carries a `user`
+        role assertion.
+      security:
+        - bearerAuth: []
+      parameters:
+        - schema:
+            type: string
+          required: true
+          name: address
+          in: path
+      responses:
+        '200':
+          description: Impersonation token
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      token:
+                        type: string
+                    required:
+                      - token
+                required:
+                  - data
+              examples:
+                success:
+                  value:
+                    data:
+                      token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJHVVNFUjg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4OCIsInJvbGUiOiJ1c2VyIn0.example
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorBody'
+              examples:
+                invalidAddress:
+                  value:
+                    error:
+                      code: validation_error
+                      details:
+                        - code: too_small
+                          message: Address must be a non-empty string
+                          path:
+                            - address
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorBody'
+              examples:
+                notAdmin:
+                  value:
+                    error:
+                      code: forbidden
+                rateLimited:
+                  value:
+                    error:
+                      code: rate_limit_exceeded
   /api/admin/audit:
     get:
       operationId: getAdminAuditLog
diff --git a/src/openapi.yaml b/src/openapi.yaml
index beccbe7f..13c43a5c 100644
--- a/src/openapi.yaml
+++ b/src/openapi.yaml
@@ -3356,6 +3356,77 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/ErrorBody'
+  /api/admin/users/{address}/impersonate:
+    post:
+      operationId: impersonateUser
+      tags:
+        - Admin
+      summary: Generate an impersonation JWT for a user (admin only)
+      description: >-
+        Admin-only endpoint that creates an audit-logged JWT allowing the
+        caller to act as the target user. The generated token carries a `user`
+        role assertion.
+      security:
+        - bearerAuth: []
+      parameters:
+        - schema:
+            type: string
+          required: true
+          name: address
+          in: path
+      responses:
+        '200':
+          description: Impersonation token
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      token:
+                        type: string
+                    required:
+                      - token
+                required:
+                  - data
+              examples:
+                success:
+                  value:
+                    data:
+                      token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJHVVNFUjg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4ODg4OCIsInJvbGUiOiJ1c2VyIn0.example
+        '400':
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ValidationErrorBody'
+              examples:
+                invalidAddress:
+                  value:
+                    error:
+                      code: validation_error
+                      details:
+                        - code: too_small
+                          message: Address must be a non-empty string
+                          path:
+                            - address
+        '403':
+          description: Forbidden
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorBody'
+              examples:
+                notAdmin:
+                  value:
+                    error:
+                      code: forbidden
+                rateLimited:
+                  value:
+                    error:
+                      code: rate_limit_exceeded
   /api/admin/audit:
     get:
       operationId: getAdminAuditLog