[DO NOT MERGE] add demo migrations to OpenApiDocsViewV2

[zchsh]

Warning

This PR is not meant to be merged. It's meant as a reference of the remaining work to be done to migrate to our new OpenAPI docs template.

🔗 Relevant links

• Preview link 🔎
• Asana task 🎟️

🗒️ What

This PR demos the migration work needed to move to our new OpenAPI docs view, which splits operations to individual pages.

One way to move the migration work forward would be to take each individual commit on this branch, and split it out to a separate PR. Each of these PRs could be worked on and then merged to main in the original commit order.

To get more specific, each of the following commits could be split to a separate PR. Each of these could be framed as a separate task, though there are definitely some dependencies here to be aware of. I've tried my best to think about these dependencies and note them below.

• Migrate /hcp/api-docs/vault-secrets
  • Migrate HCP Vault Secrets to split OpenAPI view #2631
• Replace old OpenAPI preview tool with new one
  • Currently https://developer.hashicorp.services/open-api-docs-preview serves the preview tool for our old template, this commit deprecates that old preview tool, and uses the same URL for a new preview tool.
  • Note this PR has no dependencies, it could be picked up and merged immediately
• Support getOperationTitle in OpenAPI docs view v2
  • Also implemented in add API docs for HCP RBAC #2588, if that PR merges to main first, then this commit could be dropped
  • Note this PR has no dependencies, it could be picked up and merged immediately
• Migrate /boundary/api-docs
  • Dependent on the implementation of getOperationTitle
• Remove now-unused api-docs-view
  • Dependant on the migration of /boundary/api-docs being complete
• Migrate /hcp/api-docs/consul
• Migrate /hcp/api-docs/identity
  • Dependent on the implementation of getOperationTitle
• Migrate /hcp/api-docs/packer
  • Dependent on the implementation of getOperationTitle
• Migrate /hcp/api-docs/vagrant-box-registry
• Migrate /hcp/api-docs/waypoint
  • Dependent on the implementation of getOperationTitle
• Migrate /hcp/api-docs/webhook
  • Dependent on the implementation of getOperationTitle
• Clean up to remove old open-api-docs-view
• Rename new OpenAPI view to remove v2

🤷 Why

To provide a reference for the remaining work to be done to migrate to our new OpenAPI docs template.

📸 Design Screenshots

/hcp/api-docs/vault-secrets

HCP Vault Secrets is the first set of OpenAPI docs we expect to migrate to our new template. We have a PR up here:

• Migrate HCP Vault Secrets to split OpenAPI view #2631

Note

The landing page is a little empty, due to the short description that HCP Vault Secrets has set in its spec (ref). See the HCP Consul and Boundary examples below for longer descriptions, with full markdown support.

Landing	Operation

/boundary/api-docs

The upstream Boundary API docs use an even older OpenAPI template (the first one we ever implemented!). It'll be a bit of a jump to go straight to our newest template, hopefully in a good way.

Landing	Operation

/hcp/api-docs/consul

Note

Consul has been included as an example of an HCP use of the new template that has more specific needs. In Consul's case, authors want to omit a specific versions of the OpenAPI spec, despite that file being available in the source hashicorp/hcp-specs repo. We've implemented a shim that handles this in the page file for the HCP Consul API specs.

Landing	Operation

/hcp/api-docs/identity

Landing	Operation

/hcp/api-docs/packer

Landing	Operation

/hcp/api-docs/vagrant-box-registry

Landing	Operation

/hcp/api-docs/waypoint

Landing	Operation

/hcp/api-docs/webhook

Landing	Operation

🧪 Testing

Review the migrated pages. Each page should provide an experience that's equivalent to the upstream page. Of course, the migrated pages have their operations split to separate URLs. As well, the sidebar filter has been intentionally omitted, per 🎟️ Remove sidebar filtering, redundant with global search.

• /hcp/api-docs/vault-secrets - compare to https://developer.hashicorp.com/hcp/api-docs/vault-secrets
• /boundary/api-docs - compare to https://developer.hashicorp.com/boundary/api-docs
• /hcp/api-docs/consul - compare to https://developer.hashicorp.com/hcp/api-docs/consul
• /hcp/api-docs/identity - compare to https://developer.hashicorp.com/hcp/api-docs/identity
• /hcp/api-docs/packer - compare to https://developer.hashicorp.com/hcp/api-docs/packer
• /hcp/api-docs/vagrant-box-registry - compare to https://developer.hashicorp.com/hcp/api-docs/vagrant-box-registry
• /hcp/api-docs/waypoint - compare to https://developer.hashicorp.com/hcp/api-docs/waypoint
• /hcp/api-docs/webhook - compare to https://developer.hashicorp.com/hcp/api-docs/webhook

The preview tool has also been shifted to the previously used URL, since V2 will no longer be a helpful identifier once we've fully deprecated the old version of the preview tool

• /open-api-docs-preview

💭 Anything else?

We have a parallel PR that adds the net-new OpenAPI docs for HCP RBAC. There's a bit of duplicative work in that PR, if it merges to main first, then we'll have already shipped the getOperationTitle feature.

• add API docs for HCP RBAC #2588

[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	Nov 21, 2024 6:59pm

[github-actions]

📦 Next.js Bundle Analysis

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

New Page Added

The following page was added to the bundle from the code in this PR:

Page	Size (compressed)	First Load
/open-api-docs-preview/[[...page]]	158.99 KB	353.51 KB

Eight Pages Changed Size

The following pages changed size from the code in this PR compared to its base branch:

Page	Size (compressed)	First Load
/boundary/api-docs/[[...page]]	154.19 KB (🟢 -5.51 KB)	348.71 KB
/hcp/api-docs/consul/[[...page]]	154.19 KB (🟢 -2.66 KB)	348.71 KB
/hcp/api-docs/identity/[[...page]]	154.19 KB (🟢 -2.65 KB)	348.72 KB
/hcp/api-docs/packer/[[...page]]	154.19 KB (🟢 -2.66 KB)	348.71 KB
/hcp/api-docs/vagrant-box-registry/[[...page]]	154.2 KB (🟢 -2.66 KB)	348.73 KB
/hcp/api-docs/vault-secrets/[[...page]]	154.2 KB (🟢 -2.66 KB)	348.72 KB
/hcp/api-docs/waypoint/[[...page]]	154.19 KB (🟢 -2.66 KB)	348.72 KB
/hcp/api-docs/webhook/[[...page]]	154.19 KB (🟢 -2.66 KB)	348.71 KB

Details

Only the gzipped size is provided here based on an expert tip.

First Load is the size of the global bundle plus the bundle for the individual page. If a user were to show up to your website and land on a given page, the first load size represents the amount of javascript that user would need to download. If next/link is used, subsequent page loads would only need to download that page's bundle (the number in the "Size" column), since the global bundle has already been downloaded.

Any third party scripts you have added directly to your app using the <script> tag are not accounted for in this analysis

Next to the size is how much the size has increased or decreased compared with the base branch of this PR. If this percentage has increased by 20% or more, there will be a red status indicator applied, indicating that special attention should be given to this.