Skip to content

Commit

Permalink
fix(swagger): Revise API docs for redocusaurus support
Browse files Browse the repository at this point in the history 
Because:

* values set for description and notes in hapi-swagger are converted to values for summary and description, respectively, in the autogenerated swagger.json file. This causes endpoints to be mislabeled with redocusaurus

This commit:

* revises the values of description and notes for all endpoints
  • Loading branch information
@xlisachan
xlisachan committed May 18, 2022
1 parent b465f92 commit 07b2a0c
Show file tree
Hide file tree
Showing 16 changed files with 191 additions and 130 deletions.
27 changes: 15 additions & 12 deletions packages/fxa-auth-server/docs/swagger/account-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ const TAGS_ACCOUNT = {

const ACCOUNT_CREATE_POST = {
...TAGS_ACCOUNT,
description: '/account/create',
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.
Expand All @@ -37,6 +38,7 @@ const ACCOUNT_CREATE_POST = {

const ACCOUNT_LOGIN_POST = {
...TAGS_ACCOUNT,
description: '/account/login',
notes: [
'Obtain a `sessionToken` and, optionally, a `keyFetchToken` if `keys=true`.',
],
Expand Down Expand Up @@ -68,10 +70,10 @@ const ACCOUNT_LOGIN_POST = {

const ACCOUNT_STATUS_GET = {
...TAGS_ACCOUNT,
description: '🔒🔓 sessionToken',
description: '/account/status',
notes: [
dedent`
🔒🔓 Optionally HAWK-authenticated with session token
🔒🔓 Optionally authenticated with session token
Gets the status of an account.
`,
Expand All @@ -92,17 +94,18 @@ const ACCOUNT_STATUS_GET = {

const ACCOUNT_STATUS_POST = {
...TAGS_ACCOUNT,
description: '/account/status',
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).',
],
};

const ACCOUNT_PROFILE_GET = {
...TAGS_ACCOUNT,
description: '🔒 sessionToken, oauthToken',
description: '/account/profile',
notes: [
dedent`
🔒 authenticated with OAuth bearer token or HAWK-authenticated with session token
🔒 Authenticated with OAuth bearer token or authenticated with session token
Get the email and locale of a user.
Expand All @@ -118,10 +121,10 @@ const ACCOUNT_PROFILE_GET = {

const ACCOUNT_KEYS_GET = {
...TAGS_ACCOUNT,
description: '🔒 keyFetchToken',
description: '/account/keys',
notes: [
dedent`
🔒 HAWK-authenticated with key fetch token
🔒 Authenticated with key fetch token
Get the base-16 bundle of encrypted \`kA|wrapKb\`. The return value must be decrypted with a key derived from \`keyFetchToken\`, then \`wrapKb\` must be further decrypted with a key derived from the user's password.
Expand All @@ -146,7 +149,7 @@ const ACCOUNT_KEYS_GET = {

const ACCOUNT_UNLOCK_RESEND_CODE_POST = {
...TAGS_ACCOUNT,
description: 'deprecated',
description: '/account/unlock/resend_code',
notes: ['This endpoint is deprecated.'],
plugins: {
'hapi-swagger': {
Expand All @@ -165,7 +168,7 @@ const ACCOUNT_UNLOCK_RESEND_CODE_POST = {

const ACCOUNT_UNLOCK_VERIFY_CODE_POST = {
...TAGS_ACCOUNT,
description: 'deprecated',
description: '/account/unlock/verify_code',
notes: ['This endpoint is deprecated.'],
plugins: {
'hapi-swagger': {
Expand All @@ -184,10 +187,10 @@ const ACCOUNT_UNLOCK_VERIFY_CODE_POST = {

const ACCOUNT_RESET_POST = {
...TAGS_ACCOUNT,
description: '🔒 accountResetToken',
description: '/account/reset',
notes: [
dedent`
🔒 HAWK-authenticated with account reset token
🔒 Authenticated with account reset token
This sets the account password and resets \`wrapKb\` to a new random value.
Expand All @@ -212,10 +215,10 @@ const ACCOUNT_RESET_POST = {

const ACCOUNT_DESTROY_POST = {
...TAGS_ACCOUNT,
description: '🔒🔓 sessionToken',
description: '/account/destroy',
notes: [
dedent`
🔒🔓 Optionally HAWK-authenticated with session token
🔒🔓 Optionally authenticated with session token
Deletes an account. All stored data is erased. The client should seek user confirmation first. The client should erase data stored on any attached services before deleting the user's account data.
`,
Expand Down
36 changes: 18 additions & 18 deletions packages/fxa-auth-server/docs/swagger/devices-and-sessions-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ const TAGS_DEVICES_AND_SESSIONS = {

const ACCOUNT_ATTACHED_CLIENTS_GET = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken',
description: '/account/attached_clients',
notes: [
dedent`
🔒 HAWK-authenticated with session token.
🔒 Authenticated with session token
Returns an array listing all the clients connected to the authenticated user's account, including devices, OAuth clients, and web sessions.
Expand All @@ -32,10 +32,10 @@ const ACCOUNT_ATTACHED_CLIENTS_GET = {

const ACCOUNT_ATTACHED_CLIENT_DESTROY_POST = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken',
description: '/account/attached_client/destroy',
notes: [
dedent`
🔒 HAWK-authenticated with session token.
🔒 Authenticated with session token
Destroy all tokens held by a connected client, disconnecting it from the user's account.
Expand All @@ -46,10 +46,10 @@ const ACCOUNT_ATTACHED_CLIENT_DESTROY_POST = {

const ACCOUNT_DEVICE_POST = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken, refreshToken',
description: '/account/device',
notes: [
dedent`
🔒 HAWK-authenticated with session token or authenticated with OAuth refresh token
🔒 Authenticated with session token or OAuth refresh token
Creates or updates the [**device registration**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/device_registration.md) record associated with the auth token used for this request. At least one of \`name\`, \`type\`, \`pushCallback\` or the tuple \`{ pushCallback, pushPublicKey, pushAuthKey }\` must be present. Beware that if you provide \`pushCallback\` without the pair \`{ pushPublicKey, pushAuthKey }\`, both of those keys will be reset to the empty string.
Expand All @@ -76,10 +76,10 @@ const ACCOUNT_DEVICE_POST = {

const ACCOUNT_DEVICE_COMMANDS_GET = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken, refreshToken',
description: '/account/device/commands',
notes: [
dedent`
🔒 HAWK-authenticated with session token or authenticated with OAuth refresh token.
🔒 Authenticated with session token or authenticated with OAuth refresh token.
Fetches commands enqueued for the current device by prior calls to \`/account/devices/invoke_command\`. The device can page through the enqueued commands by using the \`index\` and \`limit\` parameters.
Expand All @@ -90,10 +90,10 @@ const ACCOUNT_DEVICE_COMMANDS_GET = {

const ACCOUNT_DEVICES_INVOKE_COMMAND_POST = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken, refreshToken',
description: '/account/devices/invoke_command',
notes: [
dedent`
🔒 HAWK-authenticated with session token or authenticated with OAuth refresh token.
🔒 Authenticated with session token or authenticated with OAuth refresh token.
Enqueues a command to be invoked on a target device.
Expand All @@ -116,10 +116,10 @@ const ACCOUNT_DEVICES_INVOKE_COMMAND_POST = {

const ACCOUNT_DEVICES_NOTIFY_POST = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken, refreshToken',
description: '/account/devices/notify',
notes: [
dedent`
🔒 HAWK-authenticated with session token or authenticated with OAuth refresh token.
🔒 Authenticated with session token or authenticated with OAuth refresh token.
Notifies a set of devices associated with the user's account of an event by sending a browser push notification. A typical use case would be to send a notification to another device after sending a tab with Sync, so it can sync too and display the tab in a timely manner.
`,
Expand All @@ -146,10 +146,10 @@ const ACCOUNT_DEVICES_NOTIFY_POST = {

const ACCOUNT_DEVICES_GET = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken, refreshToken',
description: '/account/devices',
notes: [
dedent`
🔒 HAWK-authenticated with session token or authenticated with OAuth refresh token.
🔒 Authenticated with session token or authenticated with OAuth refresh token.
Returns an array of registered device objects for the authenticated user.
`,
Expand All @@ -158,12 +158,12 @@ const ACCOUNT_DEVICES_GET = {

const ACCOUNT_SESSIONS_GET = {
...TAGS_DEVICES_AND_SESSIONS,
description: 'deprecated (🔒 sessionToken)',
description: '/account/sessions',
notes: [
dedent`
[**DEPRECATED**]: Please use [**/account/attached_clients**](https://github.com/mozilla/fxa/blob/main/packages/fxa-auth-server/docs/api.md#get-accountattached_clients) instead.
🔒 HAWK-authenticated with session token.
🔒 Authenticated with session token.
Returns an array of session objects for the authenticated user.
`,
Expand All @@ -177,10 +177,10 @@ const ACCOUNT_SESSIONS_GET = {

const ACCOUNT_DEVICE_DESTROY_POST = {
...TAGS_DEVICES_AND_SESSIONS,
description: '🔒 sessionToken, refreshToken',
description: '/account/device/destroy',
notes: [
dedent`
🔒 HAWK-authenticated with session token or authenticated with OAuth refresh token
🔒 Authenticated with session token or authenticated with OAuth refresh token
Destroys a device record and the associated \`sessionToken\` for the authenticated user.
`,
Expand Down
36 changes: 19 additions & 17 deletions packages/fxa-auth-server/docs/swagger/emails-api.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,16 @@ const TAGS_EMAILS = {

const EMAILS_REMINDERS_CAD_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/emails/reminders/cad',
notes: ['🔒 Authenticated with session token'],
};

const RECOVERY_EMAIL_STATUS_GET = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email/status',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
Returns the 'verified' status for the account's recovery email address.
Expand All @@ -44,10 +45,10 @@ const RECOVERY_EMAIL_STATUS_GET = {

const RECOVERY_EMAIL_RESEND_CODE_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email/resend_code',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
Re-sends a verification code to the account's recovery email address. The code is first sent when the account is created, but if the user thinks the message was lost or accidentally deleted, they can request a new message to be sent via this endpoint. The new message will contain the same code as the original message. When this code is provided to \`/v1/recovery_email/verify_code\`, the email will be marked as 'verified'.
Expand All @@ -70,6 +71,7 @@ const RECOVERY_EMAIL_RESEND_CODE_POST = {

const RECOVERY_EMAIL_VERIFY_CODE_POST = {
...TAGS_EMAILS,
description: '/recovery_email/verify_code',
notes: [
dedent`
Verify tokens and/or recovery emails for an account. If a valid token code is detected, the account email and tokens will be set to verified. If a valid email code is detected, the email will be marked as verified.
Expand All @@ -93,10 +95,10 @@ const RECOVERY_EMAIL_VERIFY_CODE_POST = {

const RECOVERY_EMAILS_GET = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_emails',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
Returns an array of objects containing details of the email addresses associated with the logged-in user. Currently, the primary email address is always the one from the \`accounts\` table.
`,
Expand All @@ -105,10 +107,10 @@ const RECOVERY_EMAILS_GET = {

const RECOVERY_EMAIL_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
Add a secondary email address to the logged-in account. The created address will be unverified and will not replace the primary email address.
`,
],
Expand All @@ -132,10 +134,10 @@ const RECOVERY_EMAIL_POST = {

const RECOVERY_EMAIL_DESTROY_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email/destroy',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
Delete an email address associated with the logged-in user.
`,
Expand All @@ -156,10 +158,10 @@ const RECOVERY_EMAIL_DESTROY_POST = {

const RECOVERY_EMAIL_SET_PRIMARY_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email/set_primary',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
This endpoint changes a user's primary email address. This email address must belong to the user and be verified.
`,
Expand All @@ -182,10 +184,10 @@ const RECOVERY_EMAIL_SET_PRIMARY_POST = {

const RECOVERY_EMAIL_SECONDARY_RESEND_CODE_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email/secondary/resend_code',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
This endpoint resend the otp verification to verify the secondary email.
`,
Expand All @@ -207,10 +209,10 @@ const RECOVERY_EMAIL_SECONDARY_RESEND_CODE_POST = {

const RECOVERY_EMAIL_SECONDARY_VERIFY_CODE_POST = {
...TAGS_EMAILS,
description: '🔒 sessionToken',
description: '/recovery_email/secondary/verify_code',
notes: [
dedent`
🔒 HAWK-authenticated with session token
🔒 Authenticated with session token
This endpoint verifies a secondary email using a time based (otp) code.
`,
Expand Down
Loading

0 comments on commit 07b2a0c

Please sign in to comment.