added OpenAPI response objects for sys endpoints

[lursu]

This contains a partial list of the sys endpoints that are laid out in VAULT-12144.

[dhuckins]

looks like it returns 204 no content on success

vault/vault/logical_raw.go

Line 225 in 4b8bd15

return nil, nil

[dhuckins]

think it's here
https://github.com/hashicorp/vault/blob/4b8bd15e28ad3194159e7601fe76a994688988d4/http/sys_rekey.go

(@AnPucel helped me last time one was missing iirc)

[AnPucel]

Yeah. Some of the sys calls don't have callbacks they get routed directly. If you code search the path it will show you where it gets handled, which I believe is here.

This is where some of the sys paths get handled manually

[averche]

I'm not sure where these fields are defined, but should some of them be marked as required?

[lursu]

So actually no only the three I have, this endpoint is fairly jank as it can return two totally different structures. more reading here:

vault/http/sys_rekey.go

Lines 198 to 220 in b741fa8

	// Format the response
	resp := &RekeyUpdateResponse{}
	if result != nil {
	resp.Complete = true
	resp.Nonce = req.Nonce
	resp.Backup = result.Backup
	resp.PGPFingerprints = result.PGPFingerprints
	resp.VerificationRequired = result.VerificationRequired
	resp.VerificationNonce = result.VerificationNonce
	// Encode the keys
	keys := make([]string, 0, len(result.SecretShares))
	keysB64 := make([]string, 0, len(result.SecretShares))
	for _, k := range result.SecretShares {
	keys = append(keys, hex.EncodeToString(k))
	keysB64 = append(keysB64, base64.StdEncoding.EncodeToString(k))
	}
	resp.Keys = keys
	resp.KeysB64 = keysB64
	respondOk(w, resp)
	} else {
	handleSysRekeyInitGet(ctx, core, recovery, w, r)
	}

[averche]

If the API is unstable (can return two different structures), it might be better to just not specify the fields at all. Not really sure, what do you think?

[lursu]

I think it's more helpful to return all possible fields than nothing at all.

[dhuckins]

so responses is map[int][]framework.Response
why not have

http.StatusOK: {
    {
        Description: "returned if ...",
        Fields: ...
    },
    {
        Description: "returned if ...",
        Fields: ...
    }
}