From c6fc0033eeee1fa601a12927c94c4fc97ba3e51c Mon Sep 17 00:00:00 2001
From: Anton Averchenkov <84287187+averche@users.noreply.github.com>
Date: Thu, 13 Apr 2023 18:47:14 -0400
Subject: [PATCH] openapi: Better comments for OperationPrefix/Verb/Suffix
 (#20162)

---
 sdk/framework/path.go | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/sdk/framework/path.go b/sdk/framework/path.go
index 14ea41802e..a54bd4a400 100644
--- a/sdk/framework/path.go
+++ b/sdk/framework/path.go
@@ -228,21 +228,25 @@ type DisplayAttributes struct {
 	Action string `json:"action,omitempty"`
 
 	// OperationPrefix is a hyphenated lower-case string used to construct
-	// OpenAPI OperationID. It is typically the name of the plugin.
+	// OpenAPI OperationID (prefix + verb + suffix). OperationPrefix is
+	// typically a human-readable name of the plugin or a prefix shared by
+	// multiple related endpoints.
 	OperationPrefix string `json:"operationPrefix,omitempty"`
 
-	// OperationPrefix is a hyphenated lower-case string used to construct
-	// OpenAPI OperationID. It is typically an action to be performed
-	// (e.g. "generate", "sign", "login", etc.). If not specified, the verb
-	// defaults to `logical.Operation.String()` (e.g. "read", "delete", etc.).
+	// OperationVerb is a hyphenated lower-case string used to construct
+	// OpenAPI OperationID (prefix + verb + suffix). OperationVerb is typically
+	// an action to be performed (e.g. "generate", "sign", "login", etc.). If
+	// not specified, the verb defaults to `logical.Operation.String()`
+	// (e.g. "read", "list", "delete", "write" for Create/Update)
 	OperationVerb string `json:"operationVerb,omitempty"`
 
-	// OperationPrefix is a hyphenated lower-case string used to construct
-	// OpenAPI OperationID. It is typically the name of the resource on which
-	// the action is performed (e.g. "role", "credentials", etc.). A pipe (|)
-	// separator can be used to list different suffixes for various permutations
-	// of the `Path.Pattern` regular expression. If not specified, the suffix
-	// defaults to the `Path.Pattern` split by dashes.
+	// OperationSuffix is a hyphenated lower-case string used to construct
+	// OpenAPI OperationID (prefix + verb + suffix). It is typically the name
+	// of the resource on which the action is performed (e.g. "role",
+	// "credentials", etc.). A pipe (|) separator can be used to list different
+	// suffixes for various permutations of the `Path.Pattern` regular
+	// expression. If not specified, the suffix defaults to the `Path.Pattern`
+	// split by dashes.
 	OperationSuffix string `json:"operationSuffix,omitempty"`
 
 	// EditType is the optional type of form field needed for a property