OpenAPI: Define default response structure for ListOperations

[maxb]

Almost all Vault ListOperation responses have an identical response
schema. Update the OpenAPI generator to know this, and remove a few
instances where that standard response schema had been manually
copy/pasted into place in individual endpoints.

[maxb]

See above two auto-referenced PRs:

• Some cleanup in KV plugin repo too

• Draft PR exhibiting preview of affect on vault-client-go code generation

[cipherboy]

General commentary, but you could define the standard ListResponseWithInfo(...):

vault/sdk/logical/response.go

Lines 151 to 169 in 96bb634

	// ListResponseWithInfo is used to format a response to a list operation and
	// return the keys as well as a map with corresponding key info.
	func ListResponseWithInfo(keys []string, keyInfo map[string]interface{}) *Response {
	resp := ListResponse(keys)
	keyInfoData := make(map[string]interface{})
	for _, key := range keys {
	val, ok := keyInfo[key]
	if ok {
	keyInfoData[key] = val
	}
	}
	if len(keyInfoData) > 0 {
	resp.Data["key_info"] = keyInfoData
	}
	return resp
	}

This should get you a standard schema for a few other list endpoints, such as in SSH, PKI, and apparently some Core stuff too. :-)

[maxb]

General commentary, but you could define the standard ListResponseWithInfo(...)

However, each user of ListResponseWithInfo(...) gets to define their own schema on a case-by-case basis for the info payload values in the key_info map, therefore there is no standard schema I can apply generally - unlike the base keys field, which is standardized to be a slice of string in every case.

In this PR, I'd like to just cover what can be done centrally from sdk/framework/openapi.go.

I do see that it would be nice in future to add a helper function to abstract away the common parts of the structure created in ListResponseWithInfo(...) but it would need to have a parameter to allow each individual caller to specify their variant of the nested info structure.

[cipherboy]

@maxb said:

therefore there is no standard schema I can apply generally

I don't disagree, but many of the interfaces simply use, e.g.:

vault/builtin/logical/pki/path_fetch_issuers.go

Lines 41 to 45 in 96bb634

	"key_info": {
	Type: framework.TypeMap,
	Description: `Key info with issuer name`,
	Required: false,
	},

which seems to be a generic schema? Or is what this endpoint is doing incorrect, and there shouldn't be a generic TypeMap in the response info, and instead every inner field of key_info also defined?

[maxb]

Or is what this endpoint is doing incorrect, and there shouldn't be a generic TypeMap in the response info, and instead every inner field of key_info also defined?

Yes, this is exactly what we need to happen, if generated client libraries are to be able to render responses into endpoint specific data structures, consistent with the rest of the initiative of documenting response structures.

An additional consideration, is that there is currently no declarative specification of which endpoints actually return key_info on list - so there's no way to handle this other than adding individual configuration to each endpoint that does that.

[averche]

LGTM, thanks for the contribution!

[averche]

Actually, I just noticed there are some OpenAPI related test failures, e.g. (TestSystemBackend_OpenAPI). Could you please take a look, @maxb.

.

[maxb]

I just noticed there are some OpenAPI related test failures

Sorry about that... there are three PR checks which always fail on community PRs in this repo so I'm habituated to ignoring the red Xs :-(

Fixed.

[averche]

Sorry about that... there are three PR checks which always fail on community PRs in this repo so I'm habituated to ignoring the red Xs :-(

We should really fix these sometime :)

[averche]

Thanks for fixing the tests! 🎉