[WAYP-2783] Add support for a "hidden" tag for api-docs

[jgwhite]

🔗 Relevant links

• Preview link 🔎
• WAYP-2783 🎟️

🗒️ What

This allows us to tag RPCs as hidden to prevent them appearing in API docs.

Looks like this in practice:

rpc UI_LoadProductBanner(UI.LoadProductBannerRequest) returns (UI.LoadProductBannerResponse) {
  option (google.api.http) = {
    get: "/waypoint/2023-08-18/namespace/{namespace.id}/ui/product-banner"
  };
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
    tags: ["WaypointService", "hidden"]
  };
}

🤷 Why

We have a set of specialized RPCs in cloud-waypoint-service that are designed only to be used by the UI. We were hoping we could mark these as internal but we realized that means they don’t end up in the generated Swagger at all, and thus don’t make it to our generated API client. At Emily Persson’s wise suggestion, we are opting to tag these APIs with hidden instead, and add some special handling here to ignore methods with that tag.

🛠️ How

As you’ll see from the diff, this is a small patch to getOperationProps that skips over methods with the hidden tag.

📸 Design Screenshots

N/A

🧪 Testing

1. Visit the api-doc preview page
2. Paste the contents of Waypoint’s Swagger ¹ into the Schema source field
3. Verify that none of the UI_-prefixed methods show up

📓 Docs

Question to the reviewer: I’d like to document this tag somewhere. Where’s the best place to do so?

Footnotes

1. This is the Swagger from https://github.com/hashicorp/cloud-waypoint-service/pull/1390 ↩

[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	Sep 12, 2024 0:28am

[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 looks great to me, thank you so much! 🙌

Re: documenting the tag somewhere, that's a great question... on the web presence side we recently started up an internal docs site. I'll start some documentation on our API docs there, with a note that we need to come up with author-facing documentation as well. Maybe that could be as straightforward as another section in our internal docs site... it does required Vercel auth to view though... will think on this, and very open to suggestions!