B2B-1354: [update] add security details and cleanup

docs/b2b-edition/specs/api-v3/address/address.yaml

@@ -106,7 +106,7 @@ paths:
                     meta:
                       message: Resource not found
       operationId: get-addresses-countries-countryName-code
-      description: Get a country's info via its code/name
+      description: Get a country's info from its code/name.
       parameters:
         - schema:
             type: string
@@ -117,7 +117,7 @@ paths:
             example: '0'
           in: query
           name: searchType
-          description: 'The search type, 0: Get the country code via the input country name; 1: Get the country name via the input country code.'
+          description: 'The search type, 0: Get the country code from the input country name; 1: Get the country name from the input country code.'
           required: true
         - schema:
             type: string
@@ -223,9 +223,9 @@ paths:
                     code: 404
                     data: []
                     meta:
-                      message: Please enter a valid state name or state abbreviation for the country
+                      message: Please enter a valid state name or state abbreviation for the country.
       operationId: get-addresses-states-stateName-code
-      description: Get a state info via its code/name
+      description: Get a state's info from its code/name.
       security:
         - authToken: []
       parameters:
@@ -238,7 +238,7 @@ paths:
             example: '0'
           in: query
           name: searchType
-          description: 'The search type, 0: Get the state code via the input state name; 1: Get the state name via the input state code.'
+          description: 'The search type, 0: Get the state code from the input state name; 1: Get the state name from the input state code.'
           required: true
         - schema:
             type: string
@@ -249,7 +249,7 @@ paths:
           required: true
         - schema:
             type: string
-            example: 'US(the  searchType should be 1),United States(the searchType should be 0)'
+            example: 'US(the  searchType should be 1), United States(the searchType should be 0)'
             default: US / United States
           in: query
           name: country
@@ -421,7 +421,7 @@ paths:
               - '1'
           in: query
           name: isIncludeExtraFields
-          description: Is show extra fields in the response
+          description: Is show extra fields in the response.
         - schema:
             type: string
           in: query
@@ -451,7 +451,7 @@ paths:
             type: string
           in: query
           name: state
-          description: Address state  filter
+          description: Address state filter
         - schema:
             type: string
           in: query
@@ -975,7 +975,7 @@ paths:
                     - id: '42'
                       detail: ''
                 meta:
-                  message: 'Some companies updated failed, you can see these in errors'
+                  message: 'Some companies updated failed, you can see these in errors.'
         '404':
           description: The resource was not found.
           content:
@@ -1046,7 +1046,7 @@ paths:
                     - id: '42'
                       detail: ''
                 meta:
-                  message: 'There have some company resources not found, and the companyIds is in the errors'
+                  message: 'Some company resources are not found, and the companyIds are in the errors.'
         '409':
           description: Address was in conflict with another address. This is the result of duplicate unique values.
           content:
@@ -1109,7 +1109,7 @@ paths:
                 meta:
                   message: Company was in conflict with another company
         '413':
-          description: 'Request Entity Too Large. In normal conditions, bulk create or update method support 10 entity in once request. Another case, some fields of entity over limit.'
+          description: 'Request Entity Too Large. In normal conditions, bulk create or update method support 10 entity in once request.'
           content:
             application/json:
               schema:
@@ -1313,6 +1313,7 @@ components:
   securitySchemes:
     authToken:
       name: authToken
+      description: Required to authenticate requests. Include the token in a header parameter called `authToken`.
       type: apiKey
       in: header
 tags:

docs/b2b-edition/specs/api-v3/authentication.yaml

@@ -2,7 +2,7 @@ openapi: '3.0.0'
 info:
   title: authentication
   version: '3.0'
-  description: Api auth manage
+  description: API auth manage
 servers:
   - url: 'https://api-b2b.bigcommerce.com/api/io'
 tags:
@@ -12,7 +12,7 @@ paths:
   /auth/backend:
     parameters: []
     post:
-      summary: Get Server to Server OpenAPI tokens
+      summary: Get Server to Server Tokens
       operationId: post-auth-backend
       tags:
         - Auth
@@ -108,14 +108,14 @@ paths:
                 email:
                   type: string
                   minLength: 1
-                  description: 'Backend user email, the credential you use to log in B2B Edition APP'
+                  description: 'You can use the backend user email to log into the B2B Edition APP.'
                 password:
                   type: string
                   minLength: 1
-                  description: 'Backend user password, the credential you use to log in B2B Edition APP'
+                  description: 'You can use the backend user password to log into the B2B Edition APP.'
                 name:
                   type: string
-                  description: The token name if you want specfiy
+                  description: The token name, if you want to specify it.
               required:
                 - storeHash
                 - email
@@ -153,10 +153,10 @@ paths:
                   email: [email protected]
                   password: 1mdsafu3nf9x
         description: ''
-      description: Get Server to Server OpenAPI tokens
+      description: Get Server to Server tokens
       security: []
     delete:
-      summary: Delete Backend OpenAPI tokens
+      summary: Delete Backend API tokens
       operationId: delete-auth-backend
       responses:
         '200':
@@ -212,7 +212,7 @@ paths:
                       errMsg: No matching token was found
                     meta:
                       message: Not Found Error
-      description: Delete backend OpenAPI tokens.
+      description: Delete backend API tokens.
       security:
         - authToken: []
       requestBody:
@@ -224,7 +224,7 @@ paths:
                 email:
                   type: string
                   description: |
-                    Backend user email, the credential you use to log in B2B Edition APP. Which will be used as a query parameter.
+                    The backend user email is the credential you use to log into the B2B Edition APP, which will be used as a query parameter.
                   minLength: 1
                 name:
                   type: string
@@ -273,7 +273,7 @@ paths:
                           description: Token
                         eventChannel:
                           type: string
-                          description: 'The channel that token created from app,admin or api.'
+                          description: 'The channel of the token created from an app, admin or API.'
                   meta:
                     type: object
                     properties:
@@ -323,7 +323,7 @@ paths:
                 example-1:
                   value: {}
       operationId: get-backend-tokens
-      description: Get all Server to Server OpenAPI tokens
+      description: Get all Server to Server tokens
       parameters:
         - schema:
             type: integer
@@ -339,7 +339,7 @@ paths:
           description: Pagination offset
   /auth/storefront:
     get:
-      summary: Get a StoreFront OpenAPI AuthToken
+      summary: Get a Storefront API AuthToken
       tags:
         - Auth
       responses:
@@ -410,7 +410,7 @@ paths:
                     meta:
                       message: Invalid token header. No credentials provided.
       operationId: get-auth-storefront
-      description: Get a storeFront openAPI authToken
+      description: Get a storefront API authToken
       parameters:
         - schema:
             type: string
@@ -422,11 +422,11 @@ paths:
             type: string
           in: query
           name: channelId
-          description: The BigCommerce channel id. Do not use this parameter if you do not have opened multi-storefront
+          description: The BigCommerce channel ID. Do not use this parameter if you do not have an opened multi-storefront.
       security: []
   /auth/customers:
     post:
-      summary: Get StoreFront authToken with Credentials
+      summary: Get Storefront authToken with Credentials
       operationId: post-auth-customer
       responses:
         '200':
@@ -512,11 +512,11 @@ paths:
                   description: BC customer password
                 channelId:
                   type: number
-                  description: BigCommerce channel id
+                  description: BigCommerce channel ID
                 name:
                   type: string
                   minLength: 1
-                  description: The token name if you want to specfiy
+                  description: The token name, if you want to specify it.
               required:
                 - storeHash
                 - email
@@ -534,7 +534,7 @@ paths:
                   beginAt: 1000
                   endAt: 1721930486
         description: ''
-      description: BC customer get a authentication token
+      description: BigCommerce customer gets an authentication token
       tags:
         - Auth
       security: []
@@ -580,10 +580,10 @@ paths:
               properties:
                 customerId:
                   type: integer
-                  description: BigCommerce customer id.
+                  description: BigCommerce customer ID
                 channelId:
                   type: integer
-                  description: BigCommerce channel id
+                  description: BigCommerce channel ID
               required:
                 - customerId
             examples:
@@ -598,6 +598,8 @@ components:
   securitySchemes:
     authToken:
       name: authToken
+      description: |-
+        Required to authenticate requests. Include the token in a header parameter called `authToken`.
       type: apiKey
       in: header
 security:

docs/b2b-edition/specs/api-v3/channel/channel.yaml

@@ -1,8 +1,12 @@
 openapi: 3.0.0
 info:
-  title: channel
+  title: Channel
   version: '1.0'
-  description: Related with BigCommerce store channels. Only support 'bigcommerce' paltform and 'storefront' type.
+  description: Related with BigCommerce store channels. Only support 'bigcommerce' platform and 'storefront' type.
+  contact:
+    name: BigCommerce
+    url: 'https://www.bigcommerce.com'
+    email: [email protected]
 servers:
   - url: 'https://api-b2b.bigcommerce.com/api/v3/io'
 paths:
@@ -72,11 +76,11 @@ paths:
                   value:
                     code: 422
                     data:
-                      errMsg: Multi storefront is not enabled
+                      errMsg: Multi-storefront is not enabled
                     meta:
-                      message: Multi storefront is not enabled
+                      message: Multi-storefront is not enabled
       operationId: get-channels
-      description: get store chennels
+      description: get store channels
       security:
         - authToken: []
   '/channels/{channelId}':
@@ -86,7 +90,7 @@ paths:
         name: channelId
         in: path
         required: true
-        description: BigCommerce channel id
+        description: BigCommerce channel ID
     get:
       summary: Get a store channel
       tags:
@@ -127,7 +131,7 @@ paths:
                     meta:
                       message: SUCCESS
       operationId: get-channels-channelId
-      description: Get a store chennel
+      description: Get a store channel
 components:
   schemas:
     Channel:
@@ -148,28 +152,28 @@ components:
       properties:
         id:
           type: number
-          description: B2B Edition channel id
+          description: B2B Edition channel ID
         channelId:
           type: number
-          description: BigCommerce channel id
+          description: BigCommerce channel ID
         channelName:
           type: string
           minLength: 1
           description: Channel name
         createdAt:
           type: number
-          description: The time stamp channel was created
+          description: The timestamp when you created the channel.
         updatedAt:
           type: number
-          description: The time stamp channel was updated
+          description: The timestamp when you updated the channel.
         type:
           type: string
           minLength: 1
-          description: 'The channel type, only support "storefront" now.'
+          description: 'The channel type only supports "storefront" now.'
         platform:
           type: string
           minLength: 1
-          description: 'The channel platform, only support "bigcommerce" now'
+          description: 'The channel platform only supports "bigcommerce" now.'
         status:
           type: string
           minLength: 1
@@ -183,7 +187,7 @@ components:
         site:
           type: string
           minLength: 1
-          description: ' The domain associated with a channel'
+          description: ' The domain associated with a channel.'
         isVisible:
           type: boolean
         isEnabled:
@@ -204,6 +208,7 @@ components:
   securitySchemes:
     authToken:
       name: authToken
+      description: Required to authenticate requests. Include the token in a header parameter called `authToken`.
       type: apiKey
       in: header
 tags: