API docs parseDevices function outputs incorrectly formatted list

[rfk]

From #2429 (comment)

The API docs generator tries to parse and render this schema:

const SCHEMA = {
  id: isA.string().length(32).regex(HEX_STRING),
  location: isA.object({
    city: isA.string().optional().allow(null),
    country: isA.string().optional().allow(null),
    state: isA.string().optional().allow(null),
    stateCode: isA.string().optional().allow(null)
  }),
  name: isA.string().max(255).regex(DISPLAY_SAFE_UNICODE_WITH_NON_BMP),
  // We previously allowed devices to register with arbitrary unicode names,
  // so we can't assert DISPLAY_SAFE_UNICODE_WITH_NON_BMP in the response schema.
  nameResponse: isA.string().max(255),
  type: isA.string().max(16),
  capabilities: isA.array().items(isA.string()),
  pushCallback: validators.url({ scheme: 'https' }).regex(PUSH_SERVER_REGEX).max(255).allow(''),
  pushPublicKey: isA.string().max(88).regex(URL_SAFE_BASE_64).allow(''),
  pushAuthKey: isA.string().max(24).regex(URL_SAFE_BASE_64).allow(''),
  pushEndpointExpired: isA.boolean().strict()
}

And produces the following output:

    * `id: isA.string.length(32).regex(HEX_STRING)
    * `location`: isA.object({ city: isA.string.optional.allow(null)
    * `country`: isA.string.optional.allow(null)
    * `state`: isA.string.optional.allow(null)
    * `stateCode`: isA.string.optional.allow(null) })
    * `name`: isA.string.max(255).regex(DISPLAY_SAFE_UNICODE_WITH_NON_BMP)
    * `nameResponse`: isA.string.max(255)
    * `type`: isA.string.max(16)
    * `capabilities`: isA.array.items(isA.string)
    * `pushCallback`: validators.url({ scheme: 'https' }).regex(PUSH_SERVER_REGEX).max(255).allow('')
    * `pushPublicKey`: isA.string.max(88).regex(URL_SAFE_BASE_64).allow('')
    * `pushAuthKey`: isA.string.max(24).regex(URL_SAFE_BASE_64).allow('')
    * `pushEndpointExpired`: isA.boolean.strict

The first item, "id", is missing a closing backtick and so won't render correctly. The nested items from "location" have also been flattened to the top level of the list which makes the isA.object({ hard to read.

We may need to actually parse this nested object structure to produce nice output, rather than processing it with regexes here:

https://github.com/mozilla/fxa-auth-server/blob/master/scripts/write-api-docs.js#L831

Or add more regexes I guess :-)