VAULT-12144: add openapi responses for /sys/tools endpoints (#18626)

* add struct for /sys/tools/hash

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

* added responses for /sys/tools paths

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

* add changelog

* verify respose structure for hash

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

* verify respose structure for hash/random

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

* use newer testing funct

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

* use new test method

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

---------

Signed-off-by: Daniel Huckins <dhuckins@users.noreply.github.com>

changelog/18626.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+openapi: add openapi response definitions to /sys/tool endpoints
+```

vault/logical_system_paths.go

@@ -1542,8 +1542,21 @@ func (b *SystemBackend) toolsPaths() []*framework.Path {
 				},
 			},
 
-			Callbacks: map[logical.Operation]framework.OperationFunc{
+			Operations: map[logical.Operation]framework.OperationHandler{
-				logical.UpdateOperation: b.pathHashWrite,
+				logical.UpdateOperation: &framework.PathOperation{
+					Callback: b.pathHashWrite,
+					Responses: map[int][]framework.Response{
+						http.StatusOK: {{
+							Description: "OK",
+							Fields: map[string]*framework.FieldSchema{
+								"sum": {
+									Type:     framework.TypeString,
+									Required: true,
+								},
+							},
+						}},
+					},
+				},
 			},
 
 			HelpSynopsis:    strings.TrimSpace(sysHelp["hash"][0]),
@@ -1577,8 +1590,21 @@ func (b *SystemBackend) toolsPaths() []*framework.Path {
 				},
 			},
 
-			Callbacks: map[logical.Operation]framework.OperationFunc{
+			Operations: map[logical.Operation]framework.OperationHandler{
-				logical.UpdateOperation: b.pathRandomWrite,
+				logical.UpdateOperation: &framework.PathOperation{
+					Callback: b.pathRandomWrite,
+					Responses: map[int][]framework.Response{
+						http.StatusOK: {{
+							Description: "OK",
+							Fields: map[string]*framework.FieldSchema{
+								"random_bytes": {
+									Type:     framework.TypeString,
+									Required: true,
+								},
+							},
+						}},
+					},
+				},
 			},
 
 			HelpSynopsis:    strings.TrimSpace(sysHelp["random"][0]),

vault/logical_system_test.go

@@ -3469,10 +3469,16 @@ func TestSystemBackend_ToolsHash(t *testing.T) {
 	req.Data = map[string]interface{}{
 		"input": "dGhlIHF1aWNrIGJyb3duIGZveA==",
 	}
-	_, err := b.HandleRequest(namespace.RootContext(nil), req)
+	resp, err := b.HandleRequest(namespace.RootContext(nil), req)
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
+	schema.ValidateResponse(
+		t,
+		schema.GetResponseSchema(t, b.(*SystemBackend).Route(req.Path), req.Operation),
+		resp,
+		true,
+	)
 
 	doRequest := func(req *logical.Request, errExpected bool, expected string) {
 		t.Helper()
@@ -3483,12 +3489,21 @@ func TestSystemBackend_ToolsHash(t *testing.T) {
 		if resp == nil {
 			t.Fatal("expected non-nil response")
 		}
+
 		if errExpected {
 			if !resp.IsError() {
 				t.Fatalf("bad: got error response: %#v", *resp)
 			}
 			return
+		} else {
+			schema.ValidateResponse(
+				t,
+				schema.GetResponseSchema(t, b.(*SystemBackend).Route(req.Path), req.Operation),
+				resp,
+				true,
+			)
 		}
+
 		if resp.IsError() {
 			t.Fatalf("bad: got error response: %#v", *resp)
 		}
@@ -3554,10 +3569,16 @@ func TestSystemBackend_ToolsRandom(t *testing.T) {
 	b := testSystemBackend(t)
 	req := logical.TestRequest(t, logical.UpdateOperation, "tools/random")
 
-	_, err := b.HandleRequest(namespace.RootContext(nil), req)
+	resp, err := b.HandleRequest(namespace.RootContext(nil), req)
 	if err != nil {
 		t.Fatalf("err: %v", err)
 	}
+	schema.ValidateResponse(
+		t,
+		schema.GetResponseSchema(t, b.(*SystemBackend).Route(req.Path), req.Operation),
+		resp,
+		true,
+	)
 
 	doRequest := func(req *logical.Request, errExpected bool, format string, numBytes int) {
 		t.Helper()
@@ -3574,7 +3595,15 @@ func TestSystemBackend_ToolsRandom(t *testing.T) {
 					t.Fatalf("bad: got error response: %#v", *resp)
 				}
 				return nil
+			} else {
+				schema.ValidateResponse(
+					t,
+					schema.GetResponseSchema(t, b.(*SystemBackend).Route(req.Path), req.Operation),
+					resp,
+					true,
+				)
 			}
+
 			if resp.IsError() {
 				t.Fatalf("bad: got error response: %#v", *resp)
 			}