docs: fixes 3084

packages/auth/src/openapi/specs/id-provider.yaml

@@ -6,11 +6,11 @@ info:
     name: Apache 2.0
     identifier: Apache-2.0
   summary: Rafiki Authorization Server - Identity Provider Connection
-  description: 'The Open Payments API is secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the connection between the Rafiki Open Payments Authorization Server and an Identity Provider.'
+  description: 'The Open Payments APIs are secured via [GNAP](https://datatracker.ietf.org/doc/html/draft-ietf-gnap-core-protocol). This specification describes the interaction endpoints used between a Rafiki Open Payments authorization server and an identity provider.'
   contact:
     email: [email protected]
 servers:
-  - url: 'https://openpayments.guide/auth'
+  - url: 'https://openpayments.dev/auth'
 tags:
   - name: front-channel
     description: Redirect URLs
@@ -19,7 +19,7 @@ tags:
 paths:
   '/interact/{id}/{nonce}':
     get:
-      summary: Start user interaction
+      summary: Start user interaction session
       responses:
         '302':
           content:
@@ -52,7 +52,7 @@ paths:
           in: path
           name: nonce
           required: true
-          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker.  MUST be generated by the client instance as a unique value for this request.'
+          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
         - schema:
             type: string
           name: clientName
@@ -65,7 +65,7 @@ paths:
           in: query
           required: true
           description: 'URI of the client that created the grant'
-      description: 'To start the user interaction for grant approval, this endpoint redirects the user to an Identity provider endpoint for authentication.'
+      description: 'This endpoint is called by the client to start the user interaction session for grant approval. The endpoint redirects the user to an identity provider endpoint for authentication.'
       tags:
         - front-channel
   '/interact/{id}/{nonce}/finish':
@@ -91,7 +91,7 @@ paths:
           description: Unauthorized
         '404':
           description: Not Found
-      description: "To finish the user interaction for grant approval, this endpoint redirects the user to the client's finish url."
+      description: "This endpoint is called by the identity provider to end the user interaction and redirect the user to the client's finish URL."
       parameters:
         - schema:
             type: string
@@ -104,12 +104,12 @@ paths:
           in: path
           name: nonce
           required: true
-          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker.  MUST be generated by the client instance as a unique value for this request.'
+          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
       tags:
         - front-channel
   '/grant/{id}/{nonce}':
     get:
-      summary: Lookup Grant
+      summary: Look up grant information
       responses:
         '200':
           description: OK
@@ -123,9 +123,9 @@ paths:
                   state:
                     description: |-
                       Interaction state:
-                      * `PENDING` - Awaiting interaction from resource owner (RO)
-                      * `APPROVED` - RO approved interaction
-                      * `DENIED` - RO Rejected interaction
+                      * `PENDING` - Awaiting interaction from resource owner
+                      * `APPROVED` - Resource owner approved interaction
+                      * `DENIED` - Resource owner rejected interaction
                     type: string
                     enum:
                       - PENDING
@@ -140,7 +140,7 @@ paths:
           description: Not Found
       operationId: get-grant
       description: |
-        The Identity Provider uses this endpoint to requests the grant details associated with the provided `interactId` on the front-channel. It will then display those details to the user to either accept or deny the grant.
+        This endpoint is called by the identity provider to get the grant details associated with the `interactId` on the front-channel. The identity provider will display the details to the user to either accept or deny.
       parameters:
         - schema:
             type: string
@@ -153,7 +153,7 @@ paths:
           in: path
           name: nonce
           required: true
-          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker.  MUST be generated by the client instance as a unique value for this request.'
+          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
       tags:
         - back-channel
   '/grant/{id}/{nonce}/{choice}':
@@ -169,7 +169,7 @@ paths:
           description: Unauthorized
         '404':
           description: Not Found
-      description: The Identity Provider uses this endpoint to submit the user's choice regarding accepting or rejecting a grant to Authorization Server.
+      description: This endpoint is called by the identity provider to communicate the user's choice (acceptance or rejection) to the authorization server.
       parameters:
         - schema:
             type: string
@@ -182,7 +182,7 @@ paths:
           in: path
           name: nonce
           required: true
-          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI, must be sufficiently random to be unguessable by an attacker.  MUST be generated by the client instance as a unique value for this request.'
+          description: 'Unique value to be used in the calculation of the "hash" query parameter sent to the callback URI. Must be sufficiently random to be unguessable by an attacker. MUST be generated by the client instance as a unique value for this request.'
         - schema:
             type: string
             enum:

packages/backend/src/openapi/specs/webhooks.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 info:
   title: Rafiki Webhooks
   version: 1.1.0
-  description: 'Webhook Events fired by Rafiki'
+  description: 'Webhook events fired by Rafiki'
   contact:
     email: [email protected]
 servers:
@@ -11,113 +11,113 @@ webhooks:
   incomingPaymentCreated:
     post:
       requestBody:
-        description: Notify account servicing entity that an incoming payment was created.
+        description: Notifies the account servicing entity that an incoming payment was created. This event is purely informational.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/incomingPaymentEvent'
       responses:
         '200':
-          description: Returns a 200 status to indicate that the data was received successfully.
+          description: Data received successfully
   incomingPaymentCompleted:
     post:
       requestBody:
-        description: Notify account servicing entity that an incoming payment was completed and funds should now be withdrawn.
+        description: Notifies the account servicing entity that an incoming payment was completed and funds should be withdrawn.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/incomingPaymentEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   incomingPaymentExpired:
     post:
       requestBody:
-        description: Notify account servicing entity that an incoming payment has expired and funds should now be withdrawn.
+        description: Notifies the account servicing entity that an incoming payment has expired and funds should be withdrawn.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/incomingPaymentEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   outgoingPaymentCreated:
     post:
       requestBody:
-        description: Notify account servicing entity that an outgoing payment was created and should now be funded.
+        description: Notifies the account servicing entity that an outgoing payment was created and is awaiting funding.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/outgoingPaymentEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   outgoingPaymentCompleted:
     post:
       requestBody:
-        description: Notify account servicing entity that an outgoing payment completed. Remaining funds should be withdrawn.
+        description: Notifies the account servicing entity that an outgoing payment completed and any remaining funds should be withdrawn.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/outgoingPaymentEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   outgoingPaymentFailed:
     post:
       requestBody:
-        description: Notify account servicing entity that an outgoing payment failed and won't be retried. Funds should be withdrawn.
+        description: Notifies the account servicing entity that an outgoing payment failed, the retry was unsuccessful, and funds should be withdrawn.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/outgoingPaymentEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   walletAddressNotFound:
     post:
       requestBody:
-        description: Notify account servicing entity to create a wallet address if it can find a corresponding account in their system.
+        description: Notifies the account servicing entity to create a wallet address for the associated account in their system.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/walletAddressNotFound'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   webMonetization:
     post:
       requestBody:
-        description: Notify account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
+        description: Notifies the account servicing entity that a Web Monetization payment was received and funds should be withdrawn.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/webMonetizationEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   assetLiquidity:
     post:
       requestBody:
-        description: Notify account servicing entity that asset liquidity is low.
+        description: Notifies the account servicing entity that the liquidity for a specific asset is low.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/liquidityEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
   peerLiquidity:
     post:
       requestBody:
-        description: Notify account servicing entity that peer liquidity is low.
+        description: Notifies the account servicing entity that the liquidity for a specific peer is low.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/liquidityEvent'
       responses:
         '200':
-          description: Return a 200 status to indicate that the data was received successfully
+          description: Data was received successfully
 
 components:
   schemas:
@@ -358,10 +358,10 @@ components:
         value:
           type: string
           format: uint64
-          description: 'The value is an unsigned 64-bit integer amount, represented as a string.'
+          description: 'An unsigned 64-bit integer amount, represented as a string.'
         assetCode:
           type: string
-          description: The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
+          description: A code that indicates the underlying asset. This SHOULD be an ISO4217 currency code.
         assetScale:
           type: integer
           minimum: 0