luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Add mount path into the default generated openapi.json spec (#17839) 

The current behaviour is to only add mount paths into the generated `opeanpi.json` spec if a `generic_mount_paths` flag is added to the request. This means that we would have to maintain two different `openapi.json` files, which is not ideal. The new solution in this PR is to add `{mount_path}` into every path with a default value specified:

```diff
--    "/auth/token/accessors/": {
++    "/auth/{mount_path}/accessors/": {
      "parameters": [
        {
          "name": "mount_path",
          "description": "....",
          "in": "path",
          "schema": {
            "type": "string",
++          "default": "token"
          }
        }
      ],
```

Additionally, fixed the logic to generate the `operationId` (used to generate method names in the code generated from OpenAPI spec). It had a bug where the ID had `mountPath` in it. The new ID will look like this:

```diff
-- "operationId": "listAuthMountpathAccessors",
++ "operationId": "listTokenAccessors",
```
This commit is contained in:
Anton Averchenkov 2022-11-10 15:44:43 -05:00 committed by GitHub
parent 8ad82d9de4
commit f3aea876b9
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 126 additions and 142 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
api/plugin_helpers.go
View File

@ -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/.+$`),

3
changelog/17839.txt Normal file
View File

@ -0,0 +1,3 @@
```release-note:improvement
openapi: Add {mount_path} parameter to secret & auth paths in the generated openapi.json spec.
```

9
sdk/framework/backend.go
View File

@ -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)
}

100
sdk/framework/openapi.go
View File

@ -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)/(?P<name>regex)"
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. "(?P<name>regex)"
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
}
}
}

60
sdk/framework/openapi_test.go
View File

@ -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 {

2
sdk/framework/path.go
View File

@ -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)
}

21
sdk/framework/testdata/legacy.json vendored
View File

@ -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": {

13
sdk/framework/testdata/operations.json vendored
View File

@ -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",

11
sdk/framework/testdata/operations_list.json vendored
View File

@ -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",

15
sdk/framework/testdata/responses.json vendored
View File

@ -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",

12
vault/logical_system.go
View File

@ -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

12
vault/logical_system_test.go
View File

@ -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"},
}

4
website/content/api-docs/system/internal-specs-openapi.mdx
View File

@ -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