Changes in schema & guide (#1080)

- Moved the `AccountConvert` path so it is in alphabetical order. - Added the `AccountConvert` schema. - Small correction in `PalletStorageItem` schema. - Added swagger verification step in the CONTRIBUTING guide.
paritytech · Oct 13, 2022 · 3fa9689 · 3fa9689
1 parent eb368ae
commit 3fa9689
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 64 deletions.
diff --git a/docs/dist/app.bundle.js b/docs/dist/app.bundle.js
diff --git a/docs/src/openapi-v1.yaml b/docs/src/openapi-v1.yaml
@@ -189,6 +189,68 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /accounts/{accountId}/convert:
+    get:
+      tags:
+      - accounts
+      summary: Convert a given AccountId to an SS58 address.
+      description: Returns the SS58 prefix, the network address format, the SS58 address, and the AccountId
+        that was given as input parameter, the scheme that was used and if it is a public key or not (boolean).
+      operationId: accountConvert
+      parameters:
+      - name: accountId
+        in: path
+        description: AccountId or Public Key (hex).
+        required: true
+        schema:
+          format: AccountId or Hex
+          type: string
+      - name: scheme
+        in: query
+        description: The cryptographic scheme to be used in order to convert the AccountId to
+          an SS58 address. It can take one of three values [sr25519, ed25519, ecdsa].
+          The default scheme that is used is `sr25519` (if it is not set in the query parameter).
+        required: false
+        schema:
+          type: string
+          format: string
+          default: 'sr25519'
+      - name: prefix
+        in: query
+        description: The address prefix which can be one of the values found in the SS58-registry.
+        required: false
+        schema:
+          type: string
+          format: number
+          default: 42
+      - name: publicKey
+        in: query
+        description: Defines if the given value in the path parameter is a Public Key (hex)
+          or not (hence AccountId).
+        required: false
+        schema:
+          type: string
+          format: boolean
+          default: true
+      responses:
+        "200":
+          description: successfully converted the AccountId and retrieved the address info.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AccountConvert'
+        "400":
+          description: Invalid AccountId
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        "404":
+          description: AccountId not found
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /accounts/{accountId}/staking-info:
     get:
       tags:
@@ -367,68 +429,6 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/AccountValidation'
-  /accounts/{accountId}/convert:
-    get:
-      tags:
-      - accounts
-      summary: Convert a given AccountId to an SS58 address.
-      description: Returns the SS58 prefix, the network address format, the SS58 address, and the AccountId
-        that was given as input parameter, the scheme that was used and if it is a public key or not (boolean).
-      operationId: accountConvert
-      parameters:
-      - name: accountId
-        in: path
-        description: AccountId or Public Key (hex).
-        required: true
-        schema:
-          format: AccountId or Hex
-          type: string
-      - name: scheme
-        in: query
-        description: The cryptographic scheme to be used in order to convert the AccountId to 
-          an SS58 address. It can take one of three values [sr25519, ed25519, ecdsa].
-          The default scheme that is used is `sr25519` (if it is not set in the query parameter).
-        required: false
-        schema:
-          type: string
-          format: string
-          default: 'sr25519'
-      - name: prefix
-        in: query
-        description: The address prefix which can be one of the values found in the SS58-registry.
-        required: false
-        schema:
-          type: string
-          format: number
-          default: 42
-      - name: publicKey
-        in: query
-        description: Defines if the given value in the path parameter is a Public Key (hex)
-          or not (hence AccountId).
-        required: false
-        schema:
-          type: string
-          format: boolean
-          default: true
-      responses:
-        "200":
-          description: successfully converted the AccountId and retrieved the address info.
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AccountConvert'
-        "400":
-          description: Invalid AccountId
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
-        "404":
-          description: AccountId not found
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Error'
   /blocks:
     get:
       tags:
@@ -1500,6 +1500,30 @@ components:
             locks
           items:
             $ref: '#/components/schemas/BalanceLock'
+    AccountConvert:
+      type: object
+      properties:
+        ss58Prefix:
+          type: string
+          description: SS58 prefix based on which the account ID or Public Key (hex) is converted to an SS58 address.
+          format: unsignedInteger
+        network:
+          type: string
+          description: The network based on which the returned address is encoded. It depends on the prefix
+            that was given as a query param.
+        address:
+          type: string
+          description: The returned SS58 address which is the result of the conversion
+            of the account ID or Public Key (hex).
+        accountId:
+          type: string
+          description: The given account ID or Public Key (hex) that is converted to an SS58 address.
+        scheme:
+          type: string
+          description: The cryptographic scheme/algorithm used to encode the given account ID or Public Key (hex).
+        publicKey:
+          type: boolean
+          description: Whether the given path parameter is a Public Key (hex) or not.
     AccountStakingInfo:
       type: object
       properties:
@@ -2210,6 +2234,8 @@ components:
           example: "referendumInfoOf"
         keys:
           type: array
+          items:
+            type: string
           description: N Storage keys passed in as the `keys` query param. 
           example: ["0x00", "0x01"]
         value:

diff --git a/guides/CONTRIBUTING.md b/guides/CONTRIBUTING.md
@@ -20,7 +20,9 @@ where reviewers will be able to review your changes made.
 -   `yarn lint`: Make sure your code follows our linting rules. You can also run `yarn lint --fix` to
     automatically fix some of those errors.
 -   `yarn test`: Make sure all tests pass.
--   `yarn build:docs`: If any changes are made to the OpenApi specs make sure to rebuild the UI.
+-   If any changes are made to the OpenApi specs :
+    - Verify the changes with an editor such as swagger as mentioned in the [README](https://github.com/paritytech/substrate-api-sidecar/tree/master/docs).
+    - Run `yarn build:docs` to make sure to rebuild the UI.
 
 ## Rules