diff --git a/api/plugin_helpers.go b/api/plugin_helpers.go index 6602a044bd..c4985107da 100644 --- a/api/plugin_helpers.go +++ b/api/plugin_helpers.go @@ -37,9 +37,9 @@ const ( // path matches that path or not (useful specifically for the paths that // contain templated fields.) var sudoPaths = map[string]*regexp.Regexp{ - "/auth/token/accessors/": regexp.MustCompile(`^/auth/token/accessors/$`), - "/pki/root": regexp.MustCompile(`^/pki/root$`), - "/pki/root/sign-self-issued": regexp.MustCompile(`^/pki/root/sign-self-issued$`), + "/auth/{mount_path}/accessors/": regexp.MustCompile(`^/auth/.+/accessors/$`), + "/{mount_path}/root": regexp.MustCompile(`^/.+/root$`), + "/{mount_path}/root/sign-self-issued": regexp.MustCompile(`^/.+/root/sign-self-issued$`), "/sys/audit": regexp.MustCompile(`^/sys/audit$`), "/sys/audit/{path}": regexp.MustCompile(`^/sys/audit/.+$`), "/sys/auth/{path}": regexp.MustCompile(`^/sys/auth/.+$`), diff --git a/changelog/17839.txt b/changelog/17839.txt new file mode 100644 index 0000000000..48d5ce6e33 --- /dev/null +++ b/changelog/17839.txt @@ -0,0 +1,3 @@ +```release-note:improvement +openapi: Add {mount_path} parameter to secret & auth paths in the generated openapi.json spec. +``` diff --git a/sdk/framework/backend.go b/sdk/framework/backend.go index 73d8f14e60..7809a7e6e1 100644 --- a/sdk/framework/backend.go +++ b/sdk/framework/backend.go @@ -539,16 +539,9 @@ func (b *Backend) handleRootHelp(req *logical.Request) (*logical.Response, error // names in the OAS document. requestResponsePrefix := req.GetString("requestResponsePrefix") - // Generic mount paths will primarily be used for code generation purposes. - // This will result in dynamic mount paths being placed instead of - // hardcoded default paths. For example /auth/approle/login would be replaced - // with /auth/{mountPath}/login. This will be replaced for all secrets - // engines and auth methods that are enabled. - genericMountPaths, _ := req.Get("genericMountPaths").(bool) - // Build OpenAPI response for the entire backend doc := NewOASDocument() - if err := documentPaths(b, requestResponsePrefix, genericMountPaths, doc); err != nil { + if err := documentPaths(b, requestResponsePrefix, doc); err != nil { b.Logger().Warn("error generating OpenAPI", "error", err) } diff --git a/sdk/framework/openapi.go b/sdk/framework/openapi.go index 4659f7ae2f..abd06c5360 100644 --- a/sdk/framework/openapi.go +++ b/sdk/framework/openapi.go @@ -13,6 +13,8 @@ import ( "github.com/hashicorp/vault/sdk/logical" "github.com/hashicorp/vault/sdk/version" "github.com/mitchellh/mapstructure" + "golang.org/x/text/cases" + "golang.org/x/text/language" ) // OpenAPI specification (OAS): https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md @@ -206,16 +208,16 @@ var ( altRootsRe = regexp.MustCompile(`^\(([\w\-_]+(?:\|[\w\-_]+)+)\)(/.*)$`) // Pattern starting with alts, e.g. "(root1|root2)/(?Pregex)" cleanCharsRe = regexp.MustCompile("[()^$?]") // Set of regex characters that will be stripped during cleaning cleanSuffixRe = regexp.MustCompile(`/\?\$?$`) // Path suffix patterns that will be stripped during cleaning - nonWordRe = regexp.MustCompile(`[^\w]+`) // Match a sequence of non-word characters + nonWordRe = regexp.MustCompile(`[^a-zA-Z0-9]+`) // Match a sequence of non-word characters pathFieldsRe = regexp.MustCompile(`{(\w+)}`) // Capture OpenAPI-style named parameters, e.g. "lookup/{urltoken}", reqdRe = regexp.MustCompile(`\(?\?P<(\w+)>[^)]*\)?`) // Capture required parameters, e.g. "(?Pregex)" wsRe = regexp.MustCompile(`\s+`) // Match whitespace, to be compressed during cleaning ) // documentPaths parses all paths in a framework.Backend into OpenAPI paths. -func documentPaths(backend *Backend, requestResponsePrefix string, genericMountPaths bool, doc *OASDocument) error { +func documentPaths(backend *Backend, requestResponsePrefix string, doc *OASDocument) error { for _, p := range backend.Paths { - if err := documentPath(p, backend.SpecialPaths(), requestResponsePrefix, genericMountPaths, backend.BackendType, doc); err != nil { + if err := documentPath(p, backend.SpecialPaths(), requestResponsePrefix, backend.BackendType, doc); err != nil { return err } } @@ -224,7 +226,7 @@ func documentPaths(backend *Backend, requestResponsePrefix string, genericMountP } // documentPath parses a framework.Path into one or more OpenAPI paths. -func documentPath(p *Path, specialPaths *logical.Paths, requestResponsePrefix string, genericMountPaths bool, backendType logical.BackendType, doc *OASDocument) error { +func documentPath(p *Path, specialPaths *logical.Paths, requestResponsePrefix string, backendType logical.BackendType, doc *OASDocument) error { var sudoPaths []string var unauthPaths []string @@ -233,6 +235,11 @@ func documentPath(p *Path, specialPaths *logical.Paths, requestResponsePrefix st unauthPaths = specialPaths.Unauthenticated } + defaultMountPath := requestResponsePrefix + if requestResponsePrefix == "kv" { + defaultMountPath = "secret" + } + // Convert optional parameters into distinct patterns to be processed independently. paths := expandPattern(p.Pattern) @@ -263,16 +270,17 @@ func documentPath(p *Path, specialPaths *logical.Paths, requestResponsePrefix st // Body fields will be added to individual operations. pathFields, bodyFields := splitFields(p.Fields, path) - if genericMountPaths && requestResponsePrefix != "system" && requestResponsePrefix != "identity" { - // Add mount path as a parameter + // Add mount path as a parameter + if defaultMountPath != "system" && defaultMountPath != "identity" { p := OASParameter{ - Name: "mountPath", - Description: "Path that the backend was mounted at", + Name: "mount_path", + Description: "Path where the backend was mounted; the endpoint path will be offset by the mount path", In: "path", Schema: &OASSchema{ - Type: "string", + Type: "string", + Default: defaultMountPath, }, - Required: true, + Required: false, } pi.Parameters = append(pi.Parameters, p) @@ -341,6 +349,7 @@ func documentPath(p *Path, specialPaths *logical.Paths, requestResponsePrefix st op.Summary = props.Summary op.Description = props.Description op.Deprecated = props.Deprecated + op.OperationID = constructOperationID(string(opType), path, defaultMountPath) // Add any fields not present in the path as body parameters for POST. if opType == logical.CreateOperation || opType == logical.UpdateOperation { @@ -515,6 +524,19 @@ func constructRequestName(requestResponsePrefix string, path string) string { return b.String() } +func constructOperationID(method, path, defaultMountPath string) string { + // title caser + title := cases.Title(language.English) + + // Space-split on non-words, title case everything, recombine + id := nonWordRe.ReplaceAllLiteralString(strings.ToLower(path), " ") + id = fmt.Sprintf("%s %s", defaultMountPath, id) + id = title.String(id) + id = strings.ReplaceAll(id, " ", "") + + return method + id +} + func specialPathMatch(path string, specialPaths []string) bool { // Test for exact or prefix match of special paths. for _, sp := range specialPaths { @@ -727,61 +749,3 @@ func cleanResponse(resp *logical.Response) *cleanedResponse { Headers: resp.Headers, } } - -// CreateOperationIDs generates unique operationIds for all paths/methods. -// The transform will convert path/method into camelcase. e.g.: -// -// /sys/tools/random/{urlbytes} -> postSysToolsRandomUrlbytes -// -// In the unlikely case of a duplicate ids, a numeric suffix is added: -// -// postSysToolsRandomUrlbytes_2 -// -// An optional user-provided suffix ("context") may also be appended. -func (d *OASDocument) CreateOperationIDs(context string) { - opIDCount := make(map[string]int) - var paths []string - - // traverse paths in a stable order to ensure stable output - for path := range d.Paths { - paths = append(paths, path) - } - sort.Strings(paths) - - for _, path := range paths { - pi := d.Paths[path] - for _, method := range []string{"get", "post", "delete"} { - var oasOperation *OASOperation - switch method { - case "get": - oasOperation = pi.Get - case "post": - oasOperation = pi.Post - case "delete": - oasOperation = pi.Delete - } - - if oasOperation == nil { - continue - } - - // Space-split on non-words, title case everything, recombine - opID := nonWordRe.ReplaceAllString(strings.ToLower(path), " ") - opID = strings.Title(opID) - opID = method + strings.ReplaceAll(opID, " ", "") - - // deduplicate operationIds. This is a safeguard, since generated IDs should - // already be unique given our current path naming conventions. - opIDCount[opID]++ - if opIDCount[opID] > 1 { - opID = fmt.Sprintf("%s_%d", opID, opIDCount[opID]) - } - - if context != "" { - opID += "_" + context - } - - oasOperation.OperationID = opID - } - } -} diff --git a/sdk/framework/openapi_test.go b/sdk/framework/openapi_test.go index 8d3ecfea01..b2cf263240 100644 --- a/sdk/framework/openapi_test.go +++ b/sdk/framework/openapi_test.go @@ -271,7 +271,7 @@ func TestOpenAPI_SpecialPaths(t *testing.T) { Root: test.rootPaths, Unauthenticated: test.unauthPaths, } - err := documentPath(&path, sp, "kv", false, logical.TypeLogical, doc) + err := documentPath(&path, sp, "kv", logical.TypeLogical, doc) if err != nil { t.Fatal(err) } @@ -517,39 +517,32 @@ func TestOpenAPI_OperationID(t *testing.T) { }, } - for _, context := range []string{"", "bar"} { - doc := NewOASDocument() - err := documentPath(path1, nil, "kv", false, logical.TypeLogical, doc) - if err != nil { - t.Fatal(err) - } - err = documentPath(path2, nil, "kv", false, logical.TypeLogical, doc) - if err != nil { - t.Fatal(err) - } - doc.CreateOperationIDs(context) + doc := NewOASDocument() + err := documentPath(path1, nil, "kv", logical.TypeLogical, doc) + if err != nil { + t.Fatal(err) + } + err = documentPath(path2, nil, "kv", logical.TypeLogical, doc) + if err != nil { + t.Fatal(err) + } - tests := []struct { - path string - op string - opID string - }{ - {"/Foo/{id}", "get", "getFooId"}, - {"/foo/{id}", "get", "getFooId_2"}, - {"/foo/{id}", "post", "postFooId"}, - {"/foo/{id}", "delete", "deleteFooId"}, - } + tests := []struct { + path string + op string + opID string + }{ + {"/Foo/{id}", "get", "readSecretFooId"}, + {"/foo/{id}", "post", "updateSecretFooId"}, + {"/foo/{id}", "delete", "deleteSecretFooId"}, + } - for _, test := range tests { - actual := getPathOp(doc.Paths[test.path], test.op).OperationID - expected := test.opID - if context != "" { - expected += "_" + context - } + for _, test := range tests { + actual := getPathOp(doc.Paths[test.path], test.op).OperationID + expected := test.opID - if actual != expected { - t.Fatalf("expected %v, got %v", expected, actual) - } + if actual != expected { + t.Fatalf("expected %v, got %v", expected, actual) } } } @@ -583,7 +576,7 @@ func TestOpenAPI_CustomDecoder(t *testing.T) { } docOrig := NewOASDocument() - err := documentPath(p, nil, "kv", false, logical.TypeLogical, docOrig) + err := documentPath(p, nil, "kv", logical.TypeLogical, docOrig) if err != nil { t.Fatal(err) } @@ -646,10 +639,9 @@ func testPath(t *testing.T, path *Path, sp *logical.Paths, expectedJSON string) t.Helper() doc := NewOASDocument() - if err := documentPath(path, sp, "kv", false, logical.TypeLogical, doc); err != nil { + if err := documentPath(path, sp, "kv", logical.TypeLogical, doc); err != nil { t.Fatal(err) } - doc.CreateOperationIDs("") docJSON, err := json.MarshalIndent(doc, "", " ") if err != nil { diff --git a/sdk/framework/path.go b/sdk/framework/path.go index 8a8b1c7587..fe29a40089 100644 --- a/sdk/framework/path.go +++ b/sdk/framework/path.go @@ -317,7 +317,7 @@ func (p *Path) helpCallback(b *Backend) OperationFunc { // Build OpenAPI response for this path doc := NewOASDocument() - if err := documentPath(p, b.SpecialPaths(), requestResponsePrefix, false, b.BackendType, doc); err != nil { + if err := documentPath(p, b.SpecialPaths(), requestResponsePrefix, b.BackendType, doc); err != nil { b.Logger().Warn("error generating OpenAPI", "error", err) } diff --git a/sdk/framework/testdata/legacy.json b/sdk/framework/testdata/legacy.json index cb1f7ebd3f..81850f5e0c 100644 --- a/sdk/framework/testdata/legacy.json +++ b/sdk/framework/testdata/legacy.json @@ -21,12 +21,23 @@ "type": "string" }, "required": true + }, + { + "name": "mount_path", + "description": "Path where the backend was mounted; the endpoint path will be offset by the mount path", + "in": "path", + "schema": { + "type": "string", + "default": "secret" + } } ], "get": { - "operationId": "getLookupId", "summary": "Synopsis", - "tags": ["secrets"], + "operationId": "readSecretLookupId", + "tags": [ + "secrets" + ], "responses": { "200": { "description": "OK" @@ -34,9 +45,11 @@ } }, "post": { - "operationId": "postLookupId", "summary": "Synopsis", - "tags": ["secrets"], + "operationId": "updateSecretLookupId", + "tags": [ + "secrets" + ], "requestBody": { "content": { "application/json": { diff --git a/sdk/framework/testdata/operations.json b/sdk/framework/testdata/operations.json index 097399c02e..44f9b46186 100644 --- a/sdk/framework/testdata/operations.json +++ b/sdk/framework/testdata/operations.json @@ -34,10 +34,19 @@ "type": "string" }, "required": true + }, + { + "name": "mount_path", + "description": "Path where the backend was mounted; the endpoint path will be offset by the mount path", + "in": "path", + "schema": { + "type": "string", + "default": "secret" + } } ], "get": { - "operationId": "getFooId", + "operationId": "readSecretFooId", "tags": ["secrets"], "summary": "My Summary", "description": "My Description", @@ -58,7 +67,7 @@ ] }, "post": { - "operationId": "postFooId", + "operationId": "updateSecretFooId", "tags": ["secrets"], "summary": "Update Summary", "description": "Update Description", diff --git a/sdk/framework/testdata/operations_list.json b/sdk/framework/testdata/operations_list.json index e89622a3c4..9c6b13f821 100644 --- a/sdk/framework/testdata/operations_list.json +++ b/sdk/framework/testdata/operations_list.json @@ -33,10 +33,19 @@ "type": "string" }, "required": true + }, + { + "name": "mount_path", + "description": "Path where the backend was mounted; the endpoint path will be offset by the mount path", + "in": "path", + "schema": { + "type": "string", + "default": "secret" + } } ], "get": { - "operationId": "getFooId", + "operationId": "listSecretFooId", "tags": ["secrets"], "summary": "List Summary", "description": "List Description", diff --git a/sdk/framework/testdata/responses.json b/sdk/framework/testdata/responses.json index b0e197babe..fac2c1ce17 100644 --- a/sdk/framework/testdata/responses.json +++ b/sdk/framework/testdata/responses.json @@ -12,9 +12,20 @@ "paths": { "/foo": { "description": "Synopsis", + "parameters": [ + { + "name": "mount_path", + "description": "Path where the backend was mounted; the endpoint path will be offset by the mount path", + "in": "path", + "schema": { + "type": "string", + "default": "secret" + } + } + ], "x-vault-unauthenticated": true, "delete": { - "operationId": "deleteFoo", + "operationId": "deleteSecretFoo", "tags": ["secrets"], "summary": "Delete stuff", "responses": { @@ -24,7 +35,7 @@ } }, "get": { - "operationId": "getFoo", + "operationId": "readSecretFoo", "tags": ["secrets"], "summary": "My Summary", "description": "My Description", diff --git a/vault/logical_system.go b/vault/logical_system.go index 118762712e..1df776cd42 100644 --- a/vault/logical_system.go +++ b/vault/logical_system.go @@ -4408,14 +4408,10 @@ func (b *SystemBackend) pathInternalOpenAPI(ctx context.Context, req *logical.Re return nil, err } - context := d.Get("context").(string) - // Set up target document and convert to map[string]interface{} which is what will // be received from plugin backends. doc := framework.NewOASDocument() - genericMountPaths, _ := d.Get("generic_mount_paths").(bool) - procMountGroup := func(group, mountPrefix string) error { for mount, entry := range resp.Data[group].(map[string]interface{}) { @@ -4433,7 +4429,7 @@ func (b *SystemBackend) pathInternalOpenAPI(ctx context.Context, req *logical.Re req := &logical.Request{ Operation: logical.HelpOperation, Storage: req.Storage, - Data: map[string]interface{}{"requestResponsePrefix": pluginType, "genericMountPaths": genericMountPaths}, + Data: map[string]interface{}{"requestResponsePrefix": pluginType}, } resp, err := backend.HandleRequest(ctx, req) @@ -4487,8 +4483,8 @@ func (b *SystemBackend) pathInternalOpenAPI(ctx context.Context, req *logical.Re } } - if genericMountPaths && mount != "sys/" && mount != "identity/" { - s := fmt.Sprintf("/%s{mountPath}/%s", mountPrefix, path) + if mount != "sys/" && mount != "identity/" { + s := fmt.Sprintf("/%s{mount_path}/%s", mountPrefix, path) doc.Paths[s] = obj } else { doc.Paths["/"+mountPrefix+mount+path] = obj @@ -4510,8 +4506,6 @@ func (b *SystemBackend) pathInternalOpenAPI(ctx context.Context, req *logical.Re return nil, err } - doc.CreateOperationIDs(context) - buf, err := json.Marshal(doc) if err != nil { return nil, err diff --git a/vault/logical_system_test.go b/vault/logical_system_test.go index a890e1c17e..2aa12d76e8 100644 --- a/vault/logical_system_test.go +++ b/vault/logical_system_test.go @@ -3598,10 +3598,10 @@ func TestSystemBackend_OASGenericMount(t *testing.T) { path string tag string }{ - {"/auth/{mountPath}/lookup", "auth"}, - {"/{mountPath}/{path}", "secrets"}, + {"/auth/{mount_path}/lookup", "auth"}, + {"/{mount_path}/{path}", "secrets"}, {"/identity/group/id", "identity"}, - {"/{mountPath}/.*", "secrets"}, + {"/{mount_path}/.*", "secrets"}, {"/sys/policy", "system"}, } @@ -3683,10 +3683,10 @@ func TestSystemBackend_OpenAPI(t *testing.T) { path string tag string }{ - {"/auth/token/lookup", "auth"}, - {"/cubbyhole/{path}", "secrets"}, + {"/auth/{mount_path}/lookup", "auth"}, + {"/{mount_path}/{path}", "secrets"}, {"/identity/group/id", "identity"}, - {"/secret/.*", "secrets"}, // TODO update after kv repo update + {"/{mount_path}/.*", "secrets"}, // TODO update after kv repo update {"/sys/policy", "system"}, } diff --git a/website/content/api-docs/system/internal-specs-openapi.mdx b/website/content/api-docs/system/internal-specs-openapi.mdx index 68545600d3..d51d1f40b6 100644 --- a/website/content/api-docs/system/internal-specs-openapi.mdx +++ b/website/content/api-docs/system/internal-specs-openapi.mdx @@ -31,10 +31,6 @@ This endpoint returns a single OpenAPI document describing all paths visible to | :----- | :---------------------------- | | `GET` | `/sys/internal/specs/openapi` | -### Parameters - -- `generic_mount_paths` `(bool: false)` – Used to specify whether to use generic mount paths. If set, the mount paths will be replaced with a dynamic parameter: `{mountPath}` - ### Sample Request