Fix nested fields expression in api reference docs pages

[ArctypeZach]

Summary

Our markdown generation for API response payloads returns incomplete tables and response payloads for any response that has nested fields.

A few examples—

https://clickhouse.com/docs/cloud/manage/api/keys-api-reference

Current result:

Expected result:

Name	Type	Description
key.id	uuid	Unique API key ID.
key.name	string	Name of the key
key.state	string	State of the key: 'enabled', 'disabled'.
key.roles	array	List of roles assigned to the key. Contains at least 1 element.
key.keySuffix	string	Last 4 letters of the key.
key.createdAt	date-time	Timestamp the key was created. ISO-8601.
key.expireAt	date-time	Timestamp the key expires. If not present or is empty the key never expires. ISO-8601.
key.usedAt	date-time	Timestamp the key was used last time. If not present the key was never used. ISO-8601.
keyId	string	Generated key ID. Provided only if there was no 'hashData' in the request.
keySecret	string	Generated key secret. Provided only if there was no 'hashData' in the request.

{
  "key": {
    "id": "uuid",
    "name": "string",
    "state": "string",
    "roles": "Array",
    "keySuffix": "string",
    "createdAt": "date-time",
    "expireAt": "date-time",
    "usedAt": "date-time"
  },
  "keyId": "string",
  "keySecret": "string"
}

And another, flagged by @shribigb
https://clickhouse.com/docs/cloud/manage/api/usageCost-api-reference
Current result:

Expected result:

Name	Type	Description
grandTotalCHC	number	Grand total cost of usage in ClickHouse Credits (CHCs).
costs.dataWarehouseId	uuid	ID of the dataWarehouse this entity belongs to (or is).
costs.serviceId	uuid	ID of the service this entity belongs to (or is). Set to null for dataWarehouse entities.
costs.date	date	Date of the usage. ISO-8601 date, based on the UTC timezone.
costs.entityType	string	Type of the entity.
costs.entityId	uuid	Unique ID of the entity.
costs.entityName	string	Name of the entity.
costs.metrics.storageCHC	number	Cost of storage in ClickHouse Credits (CHCs). Applies to dataWarehouse entities.
costs.metrics.backupCHC	number	Cost of backup in ClickHouse Credits (CHCs). Applies to dataWarehouse entities.
costs.metrics.computeCHC	number	Cost of compute in ClickHouse Credits (CHCs). Applies to service and clickpipe entities.
costs.metrics.dataTransferCHC	number	Cost of data transfer in ClickHouse Credits (CHCs). Applies to clickpipe entities.
costs.metrics.publicDataTransferCHC	number	Cost of data transfer in ClickHouse Credits (CHCs). Applies to service entities.
costs.metrics.interRegionTier1DataTransferCHC	number	Cost of tier1 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities.
costs.metrics.interRegionTier2DataTransferCHC	number	Cost of tier2 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities.
costs.metrics.interRegionTier3DataTransferCHC	number	Cost of tier3 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities.
costs.metrics.interRegionTier4DataTransferCHC	number	Cost of tier4 inter-region data transfer in ClickHouse Credits (CHCs). Applies to service entities.
costs.totalCHC	number	Total cost of usage in ClickHouse Credits (CHCs) for this entity.
costs.locked	boolean	When true, the record is immutable. Unlocked records are subject to change until locked.

{
  "grandTotalCHC": 0,
  "costs": {
    "dataWarehouseId": "uuid",
    "serviceId": "uuid",
    "date": "date",
    "entityType": "string",
    "entityId": "uuid",
    "entityName": "string",
    "metrics": {
      "storageCHC": 0,
      "backupCHC": 0,
      "computeCHC": 0,
      "dataTransferCHC": 0,
      "publicDataTransferCHC": 0,
      "interRegionTier1DataTransferCHC": 0,
      "interRegionTier2DataTransferCHC": 0,
      "interRegionTier3DataTransferCHC": 0,
      "interRegionTier4DataTransferCHC": 0
    },
    "totalCHC": 0,
    "locked": "boolean"
  }
}

Resolution

The markdown generation needed a recursive function that checks if each field in the response contains properties or a ref. If the latter, it needs to extract the nested fields from the raw schema and generate some markdown for them. One dilemma is that markdown tables do not support nesting. as a result, the recursive method here will take an optional fieldPrefix arg that is appended in JS-style notation to the beginning of the final field name. taking the above usageCost as an example, a payload structure like:

{
  "grandTotalCHC": 0,
  "costs": {
      "date": "date",
      "metrics": {
        "computeCHC": 0
      }
   }
}

will return field names like:

grandTotalCHC
costs.date
costs.metrics.computeCHC

cc @rsickles - we should merge this before announcing new billing API endpoint.

[Blargian]

LGTM