feat: shorten protobufAny text in HCP Vault API docs

[zchsh]

🔗 Relevant links

• Preview link 🔎
• Asana task 🎟️

🗒️ What

Modifies the OpenAPI schema for HCP Vault Secrets to replace long descriptions in the protobufAny schema with shorter descriptions.

🤷 Why

The long descriptions for protobufAny we currently have in production feel more distracting that useful.

Ideally, we'd shorten these descriptions in the content source. However, making this adjustment isn't currently something that feels easy to reach for.

Note: once we are able to make modifications to these long descriptions at the content source, we'll plan to remove this layer of modification.

🛠️ How

• Moves massageSchemaForClient hook to happen before the OpenAPI schema is dereferenced
  • This makes it possible to modify the properties of references in a reasonable way, since they're still in one place rather than several.
• Builds out a set of schema modification utilities
  • Intent is to modify schema properties without mutating the incoming schema
  • Intent is also to let us compose different schema modification functions on a case-by-case basis... while also being able to easily explode those functions later into their composable parts if we go too far down the path of abstraction
• Implements schemaModProtobufAny, which replaces the long descriptions we want to address with shorter ones
  • Uses underlying schemaModComponent, which we could use to modify other referenced component schemas, not just protobufAny
• Abstracts out schemaModShortenHcp to replace HashiCorp Cloud Platform with HCP in OpenAPI schema titles, as this exact functionality is used across all our HCP OpenAPI docs so far

📸 Design Screenshots

Before	After

🧪 Testing

• Visit /hcp/api-docs/vault-secrets on the preview

  • Definitions for protobufAny, which are often referenced in default error responses, should be a reasonable length, yet still provide useful information

• Other OpenAPI docs views should be rendering as they are upstream, without changes

  • Note: some of these examples also have long protobufAny descriptions, but for now, we're scoping this adjustment to HCP Vault Secrets API docs only.
  • /hcp/api-docs/consul
  • /hcp/api-docs/packer
  • /hcp/api-docs/webhooks

💭 Anything else?

Not at the moment!

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
dev-portal	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 23, 2024 5:07pm

[github-actions]

📦 Next.js Bundle Analysis

This analysis was generated by the next.js bundle analysis action 🤖

This PR introduced no changes to the javascript bundle 🙌

[zchsh]

This is the main focus of this PR, the rest is mostly just refactoring to make using this function possible, and to build some consistency in schema modifications across the exist consumers of the OpenAPI docs view.

[zchsh]

@pbortnick This PR is a somewhat temporary content modification for the HCP Vault Secrets API docs!

Apart from the content change, this also seems to fix an issue where previous versions of the docs would fail incremental static regeneration, because the page response size would be big enough that the lambda rendering the page would have trouble. It seems that shortening the description here puts the page back under the threshold needed for incremental static regeneration to function as expected.

Happy to add any other context as needed! 🙇‍♂️

[pbortnick]

Looks way better!