Add more keria rest endpoints docs (#253)

Co-authored-by: Rubel Hassan Mollik <[email protected]>

src/keria/app/aiding.py

@@ -919,8 +919,32 @@ def on_get(req, rep, name):
         Parameters:
             req: falcon.Request HTTP request
             rep: falcon.Response HTTP response
-            name (str): human readable name for Hab to GET
-
+            name (str): human-readable name for Hab to GET
+        ---
+        summary: Fetch OOBI URLs of an identifier.
+        description: This endpoint fetches the OOBI URLs for a specific role associated with an identifier.
+        tags:
+        - Identifier
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The human-readable name of the identifier.
+        - in: query
+          name: role
+          schema:
+            type: string
+          required: true
+          description: The role for which to fetch the OOBI URLs. Can be a witness, controller, agent, or mailbox.
+        responses:
+            200:
+              description: Successfully fetched the OOBI URLs. The response body contains the OOBI URLs.
+            400:
+              description: Bad request. This could be due to missing or invalid parameters.
+            404:
+              description: The requested identifier was not found.
         """
         agent = req.context.agent
         if not name:
@@ -1850,6 +1874,33 @@ class GroupMemberCollectionEnd:
 
     @staticmethod
     def on_get(req, rep, name):
+        """
+        GET endpoint for group members
+        Parameters:
+            req (falcon.Request): The request object.
+            rep (falcon.Response): The response object.
+            name (str): The human-readable name of the identifier.
+
+        ---
+        summary: Fetch group member information.
+        description: This endpoint retrieves the signing and rotation members for a specific group associated with an identifier.
+        tags:
+        - Group Member
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The human-readable name of the identifier.
+        responses:
+            200:
+                description: Successfully fetched the group member information.
+            400:
+                description: Bad request. This could be due to missing or invalid parameters.
+            404:
+                description: The requested identifier was not found.
+        """
         agent = req.context.agent
 
         hab = agent.hby.habByName(name)

src/keria/app/credentialing.py

@@ -207,10 +207,24 @@ def on_get(req, rep, name, registryName):
         description: Get a single credential issuance and revocation registy
         tags:
            - Registries
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The human-readable name of the identifier.
+        - in: path
+          name: registryName
+          schema:
+            type: string
+          required: true
+          description: The human-readable name of the registry.
         responses:
            200:
               description:  credential issuance and revocation registy
-
+           404:
+            description: The requested registry was not found.
         """
         agent = req.context.agent
 
@@ -250,10 +264,35 @@ def on_put(req, rep, name, registryName):
         description: Get a single credential issuance and revocation registy
         tags:
            - Registries
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The human-readable name of the identifier.
+        - in: path
+          name: registryName
+          schema:
+            type: string
+          required: true
+          description: The human-readable name of the registry.
+        requestBody:
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    name:
+                      type: string
+                      description: The new name for the registry.
         responses:
            200:
-              description:  credential issuance and revocation registy
-
+                description:  credential issuance and revocation registy
+           400:
+                description: Bad request. This could be due to missing or invalid parameters.
+           404:
+                description: The requested registry was not found.
         """
         agent = req.context.agent
 
@@ -708,7 +747,49 @@ def on_delete(self, req, rep, name, said):
             sigs (list): list of signatures for the revocation event
         ---
         summary: Perform credential revocation
-        description: Perform credential revocation
+        description: Initiates a credential revocation for a given identifier and SAID.
+        tags:
+         - Credentials
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The human-readable alias for the AID to use as issuer.
+        - in: path
+          name: said
+          schema:
+            type: string
+          required: true
+          description: The SAID of the credential to revoke.
+        requestBody:
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    rev:
+                      type: string
+                      description: Serialized revocation event.
+                    ixn:
+                      type: string
+                      description: Serialized interaction event.
+                    rot:
+                      type: string
+                      description: Serialized rotation event.
+                    sigs:
+                      type: array
+                      items:
+                        type: string
+                      description: List of signatures for the revocation event.
+        responses:
+            200:
+                description: Credential revocation initiated successfully.
+            400:
+                description: Bad request. This could be due to invalid revocation event or other invalid parameters.
+            404:
+                description: The requested identifier or credential was not found.
         """
 
         agent = req.context.agent

src/keria/app/grouping.py

@@ -90,7 +90,52 @@ def on_post(req, rep, name):
             req (falcon.Request): HTTP request object
             rep (falcon.Response): HTTP response object
             name (str): AID of Hab to load credentials for
-
+        ---
+        summary: Create a multisig group request.
+        description: This endpoint creates a multisig request based on the provided name.
+        tags:
+        - Multisig Request
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The AID of Hab to load credentials for.
+        requestBody:
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    rot:
+                      type: object
+                      description: The rotation event.
+                    sigs:
+                      type: array
+                      items:
+                        type: string
+                      description: List of signatures for the rotation event.
+                    gid:
+                      type: string
+                      description: The group identifier.
+                    smids:
+                      type: array
+                      items:
+                        type: string
+                      description: List of signing member identifiers.
+                    rmids:
+                      type: array
+                      items:
+                        type: string
+                      description: List of recipient member identifiers.
+        responses:
+            202:
+                description: Successfully created the multisig request.
+            400:
+                description: Bad request. Bad request. This could be due to missing or invalid parameters.
+            404:
+                description: The requested identifier was not found.
         """
         agent = req.context.agent
 
@@ -159,7 +204,25 @@ def on_get(req, rep, said):
             req (falcon.Request): HTTP request object
             rep (falcon.Response): HTTP response object
             said (str): qb64 SAID of EXN multisig message.
-
+        ---
+        summary: Retrieve a specific multisig resource.
+        description: This endpoint retrieves the multisig resources based on the provided SAID.
+        tags:
+        - Multisig Resource
+        parameters:
+        - in: path
+          name: said
+          schema:
+            type: string
+          required: true
+          description: The qb64 SAID of the multisig resource to retrieve.
+        responses:
+            200:
+                description: Successfully retrieved the multisig resource.
+            400:
+                description: Bad request. This could be due to missing or invalid parameters.
+            404:
+                description: The requested multisig resource was not found.
         """
         agent = req.context.agent
         exn = agent.hby.db.exns.get(keys=(said,))

src/keria/end/ending.py

@@ -46,7 +46,37 @@ def on_get(self, _, rep, aid=None, role=None, eid=None):
             aid: qb64 identifier prefix of OOBI
             role: requested role for OOBI rpy message
             eid: qb64 identifier prefix of participant in role
-
+        ---
+        summary: Retrieve OOBI resource.
+        description: This endpoint retrieves the OOBI resource based on the provided aid, role, and eid.
+        tags:
+        - OOBI Resource
+        parameters:
+        - in: path
+          name: aid
+          schema:
+            type: string
+          required: false
+          description: The qb64 identifier prefix of OOBI.
+        - in: path
+          name: role
+          schema:
+            type: string
+          required: false
+          description: The requested role for OOBI rpy message.
+        - in: path
+          name: eid
+          schema:
+            type: string
+          required: false
+          description: The qb64 identifier prefix of participant in role.
+        responses:
+            200:
+                description: Successfully retrieved the OOBI resource.
+            400:
+                description: Bad request. This could be due to invalid or missing parameters.
+            404:
+                description: The requested OOBI resource was not found.
         """
         if not aid:
             if self.default is None:

src/keria/peer/exchanging.py

@@ -35,7 +35,50 @@ def on_post(req, rep, name):
             req (Request): falcon HTTP request object
             rep (Response): falcon HTTP response object
             name (str): human readable alias for AID context
-
+        ---
+        summary: Post an exchange message for an identifier.
+        description: This endpoint posts an exchange message to a specific named identifier.
+        tags:
+        - Exchange Message
+        parameters:
+        - in: path
+          name: name
+          schema:
+            type: string
+          required: true
+          description: The human-readable alias for the AID context.
+        requestBody:
+            content:
+              application/json:
+                schema:
+                  type: object
+                  properties:
+                    exn:
+                      type: object
+                      description: The exchange message event.
+                    sigs:
+                      type: array
+                      items:
+                        type: string
+                      description: The signatures for the exn message.
+                    atc:
+                      type: object
+                      description: The additional attachments for the exn message.
+                    rec:
+                      type: array
+                      items:
+                        type: string
+                      description: The recipients of the exn message.
+                    tpc:
+                      type: string
+                      description: The topic of the exn message.
+        responses:
+            202:
+                description: Successfully posted the exchange message.
+            400:
+                description: Bad request. This could be due to missing or invalid parameters.
+            404:
+                description: The requested identifier was not found.
         """
         agent = req.context.agent