Ignore api operations that have the hideFromPublicApi field

[chris-hut]

🔗 Relevant links

Hiding API endpoints in our public api RFC

🗒️ What

This PR implements the changes from the RFC to hide API endpoints we don't want to publicly display in our docs, but we'd like to still be available in our client SDKs (like in cloud-ui)

🤷 Why

There are some APIs that we don't want to move to our internal swagger definition, we'd like them to still exist in our sdk clients (such as cloud-ui), however we'd rather users not see these endpoints publicly in our docs. We understand the risk that any user could just look at network traffic in cloud-ui and decipher these endpoints - this is not trying to be security through obfuscation - instead prevent users from performing some actions that might get their accounts into bad states.

🛠️ How

As described in the RFC, we're using an OpenAPI custom specification extenstion to create an x-config object, which we'll populate with the hideFromPublicApi: true key value pair if we'd like to not display a certain endpoint in the public api docs.

For example:

{
  "post": {
    "summary": "Does something that we don't want in our public api ",
    "operationId": "SomeAPI_Action",
    "responses": {
      "200": {
        "description": "A successful response.",
        "schema": {
          "$ref": "#/definitions/hashicorp.cloud.someapi.ApiResponse"
        }
      },
      "default": {
        "description": "An unexpected error response.",
        "schema": {
          "$ref": "#/definitions/google.rpc.Status"
        }
      }
    },
    "parameters": [
      {
        "name": "body",
        "in": "body",
        "required": true,
        "schema": {
          "$ref": "#/definitions/hashicorp.cloud.someapi.ApiResponse"
        }
      }
    ],
    "tags": [
      "SomeApi"
    ],
    "x-config": {
      "hideFromPublicApi": true
    }
  }
}

By adding the x-config value to this API endpoint, the client sdk definitions will still include this api endpoint, but through the magic of this PR, we won't render the endpoint in the public API docs.

🧪 Testing

I'd love to write some tests for this, but not entirely sure how to, I was inspired by this PR - which wasn't a long term solution because it ended up breaking client SDK generation.

I wanted to test using the vercel's open-api-preview-docs link - but vercel is failing for me

• Pasted an hcp.swagger.json in the open-api-preview-docs link that included some hideFromPublicApis.
• An example would be cloud-resource-manager's here

So how I tested

dev-portal/src/views/open-api-docs-view/server.ts

Lines 104 to 107 in 672d571

	/**
	* Fetch, parse, and validate the OpenAPI schema for this version.
	*/
	const { sourceFile } = targetVersion

I hardcoded the sourceFile to just be the hcp.swagger.json from my branch in cloud-resource-manager:

const sourceFile = {
	owner: 'hashicorp',
	repo: 'cloud-resource-manager',
	path: 'proto-public/20191210/swagger/hcp.swagger.json',
	ref: 'a77736b0cfa4d4fd15acdcbf7fedeae2f3ef3ebf'
}

Then all API docs would just use my custom hcp.swagger.json 😅 From there, I was able to see that none of the endpoints that were marked with hideFromPublicApi were visible:

References

[vercel]

You must have Developer access to commit code to HashiCorp on Vercel. If you contact an administrator and receive Developer access, commit again to see your changes.

Learn more: https://vercel.com/docs/accounts/team-members-and-roles/access-roles#team-level-roles

[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 🙌

[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.

[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	Jan 21, 2025 9:32pm

[heatlikeheatwave]

I tested this using the instructions, although I used my own change in the hcps-specs repo (commit here). I used this (see below) instead of the example in the PR and it worked as expected (endpoint is hidden in the UI and appears in the spec).

const sourceFile = {
	owner: 'hashicorp',
	repo: 'hcp-specs',
	path: 'specs/cloud-iam/stable/2019-12-10/hcp.swagger.json',
	ref: '8f5729b7e30e083e1e16f99e1bdc90da47f07694'
}

I deployed the preview, so you should be able to test it using the open-api-docs-preview page