add API docs for HCP RBAC

[zchsh]

🔗 Relevant links

• Preview link 🔎
• Asana task 🎟️

🗒️ What

Stubs in a page for HCP RBAC API docs using the existing OpenAPI docs template.

📸 Design Screenshots

Landing	Operation

🧪 Testing

• Visit /hcp/api-docs/rbac in the preview
  • The API docs should look & function as expected based on the upstream spec file

💭 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	Nov 21, 2024 5:23pm

[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
/hcp/api-docs/rbac/[[...page]]	155.47 KB	349.99 KB

One Page Changed Size

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

Page	Size (compressed)	First Load
/open-api-docs-preview-v2/[[...page]]	159.97 KB (🟡 +468 B)	354.49 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.

[chris-hut]

After confirming with the team, this looks perfect to us!
Thanks so much!

[emilypersson1]

thank you!

[xargs-P]

Hello 👋 , I have open questions in Slack about how the data is displayed and which apis are revealed. Please hold on merging 🙏 while we sort this out.

[chris-hut]

After talking with Trevor:, could we:

• Hide the org-create API endpoint (​Create - post: ​/​resource-manager​/​projects)
• Combine the duplicate resource-manager/resources and resource-manager/organizations sections?
  

[pbortnick]

👍

[zchsh]

Hiya @chris-hut and @xargs-P ! Thanks for catching the issue with the path-based grouping. That should be sorted now!

I've also implemented some temporary shim code to delete the operation at schema.paths['/resource-manager/2019-12-10/projects'].post before rendering the document. This should hide the org-create endpoint.

For the "hidden endpoints", I think at some point very soon we'll want to find a more sustainable way to achieve this. For example, we could omit the operation entirely from the source spec file in hashicorp/hcp-specs. Or if that's not an option, and it needs to be included in that repo but hidden on our docs site, we could explore OpenAPI extensions, eg as discussed in this thread. (cc @emilypersson1 for this last bit, in case this merits a feature ticket or whatnot! 🙇 )

[emilypersson1]

I added an asana task for hiding private endpoints as a future idea. ideally we can remove the endpoint from the spec for now, but if the RBAC team needs this functionality, we can take a look at prioritizing this work!

[github-actions]

This PR is stale because it has been open 20 days with no activity. It will be closed in 5 days unless you remove the stale label or comment.

[zchsh]

I've updated this PR to use our new OpenAPI docs template. It should be an equivalent user experience to the previous template, the big change is each operation is now on a separate page (we were having issues with some specs creating super large single pages otherwise).

As mentioned earlier, we have a temporary shim code to delete the operation at schema.paths['/resource-manager/2019-12-10/projects'].post before rendering the document. I've retained this shim when moving to the new template.