Documenting Account Responses stellar#2

Taylor-at-Stellar · Sep 19, 2022 · e64a461 · e64a461
1 parent 18227da
commit e64a461
Show file tree

Hide file tree

Showing 6 changed files with 113 additions and 36 deletions.
diff --git a/openapi/components/endpoints/account.yml b/openapi/components/endpoints/account.yml
@@ -1,10 +1,15 @@
+# Notes:
+# September 19: 
+# - investigate Hal Links
+# - consult for response descriptions  
+# - skipping operations endpoint for now  
 paths:
   /accounts:
     get:
       tags:
         - account
       summary: List all Accounts
-      description: "This endpoint lists accounts by one of three filters : signer, asset, or sponsor."   
+      description: "This endpoint lists accounts by one of four filters : signer, asset, liquidity pool  or sponsor."   
       operationId: ListAllAccounts
       parameters:
         - $ref: '../parameters.yml#/components/parameters/SponserParam'
@@ -16,7 +21,14 @@ paths:
         - $ref: '../parameters.yml#/components/parameters/LimitParam'
       responses:
         '200':
-          description: OK  
+          description: "Returns accounts based on provided filter: signer , asset, sponser or liquidity pool"
+          content:
+            application/json:
+              schema:
+                allOf:
+                  -  $ref: "../schemas/linksSchema.yml#/components/schemas/Links"
+                  -  $ref: "../schemas/accountLinkSchema.yml#/components/schemas/AccountLink"
+                  -  $ref: "../schemas/accountSchema.yml#/components/schemas/Account" 
   /accounts/{account_id}:
     get:
       tags:
@@ -51,7 +63,16 @@ paths:
         - $ref: '../parameters.yml#/components/parameters/IncludeFailedParam'
       responses:
         '200':
-          description: OK   
+          description: blank
+          content:
+            application/json:
+              schema:
+                allOf:
+                  #TODO: 9/20 Compare results to Postman results, edit object as necessary
+                  -  $ref: "../schemas/linksSchema.yml#/components/schemas/Links"
+                  -  $ref: "../schemas/transactionLinkSchema.yml#/components/schemas/TransactionLink"
+                  -  $ref: "../schemas/transactionSchema.yml#/components/schemas/Transaction" 
+
   /accounts/{account_id}/operations:
     get:
       tags:

diff --git a/openapi/components/schemas/accountLinkSchema.yml b/openapi/components/schemas/accountLinkSchema.yml
@@ -3,25 +3,33 @@ components:
     AccountLink:
       type: object
       properties:
-        _links:
-          type: object
-          properties:
-            self:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            transactions:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            operations:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            payments:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            effects:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            offers:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            trades:
-              $ref: '../instance_variables.yml#/components/schemas/link'
-            data:
-              $ref: '../instance_variables.yml#/components/schemas/link'
+        _embedded:
+            type: object
+            properties:
+              records:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    _links:
+                      type: object
+                      properties:
+                        self:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        transactions:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        operations:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        payments:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        effects:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        offers:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        trades:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
+                        data:
+                          $ref: '../instance_variables.yml#/components/schemas/link'
       required:
         - self
         - transactions

diff --git a/openapi/components/schemas/linksSchema.yml b/openapi/components/schemas/linksSchema.yml
@@ -0,0 +1,18 @@
+components:
+  schemas:
+    Links:
+      type: object
+      properties:
+        _links:
+          type: object
+          properties:
+            self:
+              $ref: '../instance_variables.yml#/components/schemas/link'
+            next:
+              $ref: '../instance_variables.yml#/components/schemas/link'
+            prev:
+              $ref: '../instance_variables.yml#/components/schemas/link'
+    required:
+      - self
+      - next
+      - prev      
diff --git a/openapi/components/schemas/transactionLinkSchema.yml b/openapi/components/schemas/transactionLinkSchema.yml
@@ -0,0 +1,31 @@
+# Sept 19: I have not determined how the links schema works in OpenApo
+# yet, therefore I am not sure the links will stay in this format.
+components:
+    schemas:
+      TransactionLink:
+        properties:
+          self:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          account:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          ledger:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          operations:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          effects: 
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          precedes:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          succeeds:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+          transaction:
+            $ref: '../instance_variables.yml#/components/schemas/link'
+      required:
+        - self
+        - account
+        - ledger
+        - operations
+        - effects
+        - precedes
+        - succeeds
+        - transaction
diff --git a/openapi/main.yml b/openapi/main.yml
@@ -4,9 +4,9 @@ info:
   version: 0.0.1
 
 servers:
-  - url: https://horizon.stellar.org/
+  - url: https://horizon.stellar.org
     description: The main network
-  - url: https://horizon-testnet.stellar.org/ 
+  - url: https://horizon-testnet.stellar.org 
     description: The test network    
 tags:
   - name: account
@@ -16,23 +16,21 @@ tags:
 
 paths:
    /accounts:
-    $ref: '../openapi/components/endpoints/account.yml#/paths/~1accounts'
+      $ref: '../openapi/components/endpoints/account.yml#/paths/~1accounts'
    /accounts/{account_id}:
-    $ref: '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}'
+      $ref: '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}'
    /accounts/{account_id}/transactions:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1transactions'
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1transactions'
    /accounts/{account_id}/operations:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1operations'
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1operations'
    /accounts/{account_id}/payments:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1payments'
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1payments'
    /accounts/{account_id}/effects:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1effects'
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1effects'
    /accounts/{account_id}/offers:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1offers'
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1offers'
    /accounts/{account_id}/trades:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1trades'
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1trades'
    /accounts/{account_id}/data/{key}:
-    $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1data~1{key}'
-
-
-
+      $ref : '../openapi/components/endpoints/account.yml#/paths/~1accounts~1{account_id}~1data~1{key}'
+
diff --git a/redocly.yaml b/redocly.yaml
@@ -20,6 +20,7 @@ lint:
     no-enum-type-mismatch: error
     no-identical-paths: error
     no-ambiguous-paths: error
+    security-defined: off
 
 features.openapi:
   generateCodeSamples: