Remove 'Unpublished: true' inconsistently applied to sys/internal/* endpoints

[maxb]

Is your feature request related to a problem? Please describe.

I am writing a tool to consume Vault's automatic OpenAPI (sys/internal/specs/openapi) for validating policies.

The Vault OpenAPI lists almost but not all of the operations its endpoints support. For some reason, 5 of the sys/internal/* APIs are marked 'Unpublished: true' in the code (https://github.com/hashicorp/vault/blob/main/vault/logical_system_paths.go) concealing their operation data from OpenAPI:

sys/internal/ui/namespaces
sys/internal/ui/resultant-acl
sys/internal/counters/{requests,tokens,entities}

It's not just because they are internal, as other sys/internal/ endpoints are published.

Some of the sys/internal/ APIs marked as Unpublished in the code, are even part of the public documentation: https://www.vaultproject.io/api-docs/system/internal-counters

Having them in the public documentation but not the built-in Vault API Explorer (Swagger) is rather odd.

Describe the solution you'd like

Please delete the 5 occurrences of "Unpublished: true" from https://github.com/hashicorp/vault/blob/main/vault/logical_system_paths.go so that programs consuming the Vault OpenAPI - including but not limited to the built in Vault Swagger - can have full knowledge of the API.

Describe alternatives you've considered

For my own tool, I'm hardcoding extra overrides to account for the unpublished APIs - but this is inelegant, and subject to becoming out of date. For the omission of the APIs from the built-in API Explorer (Swagger), there is no workaround.

[pmmukh]

Hi @maxb ! Thank you for submitting this issue! After some discussion, the rationale for not having certain endpoints in the openApi spec was due to the fact that we don't guarantee backwards compatibility on those endpoints, but we've decided that should not preclude those endpoints from being in the openApi spec, we plan on having the lack of backwards compatibility explicitly called out in the spec descriptions to solve this problem instead. So the plan currently is to move forward with this, and publish all 5 endpoints in the spec. I'm going to start work on this shortly, will keep you posted when its fixed!

[pmmukh]

Sorry for the confusion, I don't think I'll actually get a chance to do this soon, but this should be a good issue for new community members, so I'll add the first issue label and see if someone picks it up.

[maxb]

Thanks, I will raise with my employer whether I can sign the CLA as an individual contributor, or the company needs to sign it. This might take a little while - if anyone else wants to take the idea and run with it in the meantime, that's fine too!

[saltperfect]

I would like to contribute to this issue.