Add Swagger docs at /docs and /openapi.json with split OpenAPI spec

Made-with: Cursor

backend/openapi/path-items/auth-login-npub.yaml

@@ -0,0 +1,33 @@
+post:
+  tags: [Auth]
+  summary: Sign in with npub only (limited)
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [npub]
+          properties:
+            npub:
+              type: string
+  responses:
+    "200":
+      description: Token and pubkey
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              token:
+                type: string
+              pubkey:
+                type: string
+              method:
+                type: string
+                example: npub
+    "400":
+      description: Invalid npub
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"

backend/openapi/path-items/auth-login.yaml

@@ -0,0 +1,20 @@
+post:
+  tags: [Auth]
+  summary: Sign in with NIP-98 (returns JWT)
+  security:
+    - NIP98: []
+  responses:
+    "200":
+      description: Token and pubkey
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              token:
+                type: string
+              pubkey:
+                type: string
+              method:
+                type: string
+                example: nip98

backend/openapi/path-items/auth-me.yaml

@@ -0,0 +1,23 @@
+get:
+  tags: [Auth]
+  summary: Current user from Bearer token
+  security:
+    - BearerAuth: []
+  responses:
+    "200":
+      description: Pubkey and method
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              pubkey:
+                type: string
+              method:
+                type: string
+    "401":
+      description: Unauthorized or invalid token
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"

backend/openapi/path-items/claim-confirm.yaml

@@ -0,0 +1,39 @@
+post:
+  tags: [Claim]
+  summary: Confirm quote and pay (rate limited)
+  security:
+    - BearerAuth: []
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [quote_id]
+          properties:
+            quote_id:
+              type: string
+  responses:
+    "200":
+      description: Success or already consumed
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/claim.yaml#/ConfirmResult"
+    "400":
+      description: Invalid request
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"
+    "404":
+      description: Quote not found or expired
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"
+    "502":
+      description: Lightning payment failed
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"

backend/openapi/path-items/claim-quote.yaml

@@ -0,0 +1,28 @@
+post:
+  tags: [Claim]
+  summary: Create claim quote (rate limited)
+  security:
+    - BearerAuth: []
+  requestBody:
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [lightning_address]
+          properties:
+            lightning_address:
+              type: string
+              description: user@domain.tld
+  responses:
+    "200":
+      description: Quote
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/claim.yaml#/QuoteResult"
+    "403":
+      description: Not eligible or budget exceeded
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"

backend/openapi/path-items/config.yaml

@@ -0,0 +1,10 @@
+get:
+  tags: [Public]
+  summary: Public faucet config
+  responses:
+    "200":
+      description: Faucet configuration
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/faucet.yaml#/FaucetConfig"

backend/openapi/path-items/deposit-redeem-cashu.yaml

@@ -0,0 +1,48 @@
+post:
+  tags: [Public]
+  summary: Redeem Cashu token
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          type: object
+          required: [token]
+          properties:
+            token:
+              type: string
+              description: Cashu token (cashuA... or cashuB...)
+  responses:
+    "200":
+      description: Redeem result
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              success:
+                type: boolean
+              paid:
+                type: boolean
+              amount:
+                type: integer
+              invoiceAmount:
+                type: integer
+              netAmount:
+                type: integer
+              to:
+                type: string
+              message:
+                type: string
+    "400":
+      description: Invalid token or address
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"
+    "502":
+      description: Redeem failed
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"

backend/openapi/path-items/deposit.yaml

@@ -0,0 +1,10 @@
+get:
+  tags: [Public]
+  summary: Deposit info
+  responses:
+    "200":
+      description: Lightning address and LNURLp
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/faucet.yaml#/DepositInfo"

backend/openapi/path-items/health.yaml

@@ -0,0 +1,14 @@
+get:
+  tags: [Public]
+  summary: Health check
+  responses:
+    "200":
+      description: OK
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              status:
+                type: string
+                example: ok

backend/openapi/path-items/stats.yaml

@@ -0,0 +1,16 @@
+get:
+  tags: [Public]
+  summary: Faucet stats
+  responses:
+    "200":
+      description: Stats (balance, paid, claims)
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/faucet.yaml#/Stats"
+    "500":
+      description: Internal error
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"

backend/openapi/path-items/user-refresh-profile.yaml

@@ -0,0 +1,18 @@
+post:
+  tags: [User]
+  summary: Refresh Nostr profile (kind 0)
+  security:
+    - BearerAuth: []
+  responses:
+    "200":
+      description: lightning_address and name
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/user.yaml#/UserProfile"
+    "500":
+      description: Profile fetch failed
+      content:
+        application/json:
+          schema:
+            $ref: "../components/schemas/common.yaml#/ApiError"