Additional revisions based on feedback

mozilla · Apr 25, 2022 · dc8ca1d · dc8ca1d
1 parent 24509ec
commit dc8ca1d
Show file tree

Hide file tree

Showing 54 changed files with 284 additions and 231 deletions.
diff --git a/...-auth-server/docs/swagger/account-docs.ts → ...a-auth-server/docs/swagger/account-api.ts b/...-auth-server/docs/swagger/account-docs.ts → ...a-auth-server/docs/swagger/account-api.ts
@@ -5,7 +5,12 @@
 import dedent from 'dedent';
 import TAGS from './swagger-tags';
 
+const TAGS_ACCOUNT = {
+  tags: TAGS.ACCOUNT,
+};
+
 const ACCOUNT_CREATE_POST = {
+  ...TAGS_ACCOUNT,
   notes: [
     dedent`
       Creates a user account. The client provides the email address with which this account will be associated and a stretched password. Stretching is detailed on the [**onepw**](https://github.com/mozilla/fxa-auth-server/wiki/onepw-protocol#creating-the-account) wiki page.
@@ -28,10 +33,10 @@ const ACCOUNT_CREATE_POST = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_LOGIN_POST = {
+  ...TAGS_ACCOUNT,
   notes: [
     'Obtain a `sessionToken` and, optionally, a `keyFetchToken` if `keys=true`.',
   ],
@@ -59,10 +64,10 @@ const ACCOUNT_LOGIN_POST = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_STATUS_GET = {
+  ...TAGS_ACCOUNT,
   description: '🔒🔓 sessionToken',
   notes: [
     dedent`
@@ -83,17 +88,17 @@ const ACCOUNT_STATUS_GET = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_STATUS_POST = {
+  ...TAGS_ACCOUNT,
   notes: [
     'Gets the status of an account without exposing user data through query params. This endpoint is rate limited by [**fxa-customs-server**](https://github.com/mozilla/fxa/tree/main/packages/fxa-customs-server).',
   ],
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_PROFILE_GET = {
+  ...TAGS_ACCOUNT,
   description: '🔒 sessionToken, oauthToken',
   notes: [
     dedent`
@@ -109,10 +114,10 @@ const ACCOUNT_PROFILE_GET = {
       The \`profile\` scope includes all the above sub-scopes.
     `,
   ],
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_KEYS_GET = {
+  ...TAGS_ACCOUNT,
   description: '🔒 keyFetchToken',
   notes: [
     dedent`
@@ -137,10 +142,10 @@ const ACCOUNT_KEYS_GET = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_UNLOCK_RESEND_CODE_POST = {
+  ...TAGS_ACCOUNT,
   description: 'deprecated',
   notes: ['This endpoint is deprecated.'],
   plugins: {
@@ -156,10 +161,10 @@ const ACCOUNT_UNLOCK_RESEND_CODE_POST = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_UNLOCK_VERIFY_CODE_POST = {
+  ...TAGS_ACCOUNT,
   description: 'deprecated',
   notes: ['This endpoint is deprecated.'],
   plugins: {
@@ -175,10 +180,10 @@ const ACCOUNT_UNLOCK_VERIFY_CODE_POST = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_RESET_POST = {
+  ...TAGS_ACCOUNT,
   description: '🔒 accountResetToken',
   notes: [
     dedent`
@@ -203,10 +208,10 @@ const ACCOUNT_RESET_POST = {
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
 const ACCOUNT_DESTROY_POST = {
+  ...TAGS_ACCOUNT,
   description: '🔒🔓 sessionToken',
   notes: [
     dedent`
@@ -222,16 +227,15 @@ const ACCOUNT_DESTROY_POST = {
           description: dedent`
             Failing requests may be caused by the following errors (this is not an exhaustive list):
             \`errno: 103\` - Incorrect password
-            \`errno: 138\` - Unverified sessio
+            \`errno: 138\` - Unverified session
           `,
         },
       },
     },
   },
-  tags: TAGS.ACCOUNT,
 };
 
-const accountApiDetails = {
+const API_DOCS = {
   ACCOUNT_CREATE_POST,
   ACCOUNT_DESTROY_POST,
   ACCOUNT_KEYS_GET,
@@ -244,4 +248,4 @@ const accountApiDetails = {
   ACCOUNT_UNLOCK_VERIFY_CODE_POST,
 };
 
-export default accountApiDetails;
+export default API_DOCS;
diff --git a/...docs/swagger/devices-and-sessions-docs.ts → .../docs/swagger/devices-and-sessions-api.ts b/...docs/swagger/devices-and-sessions-docs.ts → .../docs/swagger/devices-and-sessions-api.ts
@@ -5,7 +5,12 @@
 import dedent from 'dedent';
 import TAGS from './swagger-tags';
 
+const TAGS_DEVICES_AND_SESSIONS = {
+  tags: TAGS.DEVICES_AND_SESSIONS,
+};
+
 const ACCOUNT_ATTACHED_CLIENTS_GET = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken',
   notes: [
     dedent`
@@ -23,10 +28,10 @@ const ACCOUNT_ATTACHED_CLIENTS_GET = {
       These identifiers can be passed to [**/account/attached_client/destroy**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/api.md#post-accountattached_clientdestroy) in order to disconnect the client.
     `,
   ],
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_ATTACHED_CLIENT_DESTROY_POST = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken',
   notes: [
     dedent`
@@ -37,10 +42,10 @@ const ACCOUNT_ATTACHED_CLIENT_DESTROY_POST = {
       This endpoint is designed to be used in conjunction with [**/account/attached_clients**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/api.md#get-accountattached_clients). It accepts as the request body an object in the same format as returned by that endpoing, and will disconnect that client from the user's account.
     `,
   ],
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_DEVICE_POST = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken, refreshToken',
   notes: [
     dedent`
@@ -67,10 +72,10 @@ const ACCOUNT_DEVICE_POST = {
       },
     },
   },
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_DEVICE_COMMANDS_GET = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken, refreshToken',
   notes: [
     dedent`
@@ -81,10 +86,10 @@ const ACCOUNT_DEVICE_COMMANDS_GET = {
       For more details, see the [**device registration**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/device_registration.md) docs.
     `,
   ],
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_DEVICES_INVOKE_COMMAND_POST = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken, refreshToken',
   notes: [
     dedent`
@@ -107,10 +112,10 @@ const ACCOUNT_DEVICES_INVOKE_COMMAND_POST = {
       },
     },
   },
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_DEVICES_NOTIFY_POST = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken, refreshToken',
   notes: [
     dedent`
@@ -137,10 +142,10 @@ const ACCOUNT_DEVICES_NOTIFY_POST = {
       },
     },
   },
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_DEVICES_GET = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken, refreshToken',
   notes: [
     dedent`
@@ -149,10 +154,10 @@ const ACCOUNT_DEVICES_GET = {
       Returns an array of registered device objects for the authenticated user.
     `,
   ],
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_SESSIONS_GET = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: 'deprecated (🔒 sessionToken)',
   notes: [
     dedent`
@@ -168,10 +173,10 @@ const ACCOUNT_SESSIONS_GET = {
       deprecated: true,
     },
   },
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
 const ACCOUNT_DEVICE_DESTROY_POST = {
+  ...TAGS_DEVICES_AND_SESSIONS,
   description: '🔒 sessionToken, refreshToken',
   notes: [
     dedent`
@@ -180,10 +185,9 @@ const ACCOUNT_DEVICE_DESTROY_POST = {
       Destroys a device record and the associated \`sessionToken\` for the authenticated user.
     `,
   ],
-  tags: TAGS.DEVICES_AND_SESSIONS,
 };
 
-const devicesAndSessionsApiDetails = {
+const API_DOCS = {
   ACCOUNT_ATTACHED_CLIENT_DESTROY_POST,
   ACCOUNT_ATTACHED_CLIENTS_GET,
   ACCOUNT_DEVICE_COMMANDS_GET,
@@ -195,4 +199,4 @@ const devicesAndSessionsApiDetails = {
   ACCOUNT_SESSIONS_GET,
 };
 
-export default devicesAndSessionsApiDetails;
+export default API_DOCS;