[8.x][OpenAPI] Edit summaries for security APIs (#3035) (#3046)

Author: lcawl

output/openapi/elasticsearch-openapi.json

@@ -258,6 +258,7 @@ lowercase-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{bra
 mapping-date-format,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-date-format.html
 mapping-meta-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-meta-field.html
 mapping-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-fields.html
+mapping-roles,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-roles.html
 mapping-settings-limit,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-settings-limit.html
 mapping-source-field,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping-source-field.html
 mapping,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/mapping.html
@@ -569,6 +570,8 @@ security-api-saml-logout,https://www.elastic.co/guide/en/elasticsearch/reference
 security-api-saml-prepare-authentication,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-prepare-authentication.html
 security-api-saml-sp-metadata,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-saml-sp-metadata.html
 security-api-ssl,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-api-ssl.html
+security-privileges,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/security-privileges.html
+service-accounts,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/service-accounts.html
 set-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/set-processor.html
 shape,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/shape.html
 simulate-pipeline-api,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/simulate-pipeline-api.html

output/openapi/elasticsearch-serverless-openapi.json

@@ -21,7 +21,9 @@ import { GrantType } from '@security/_types/GrantType'
 import { RequestBase } from '@_types/Base'
 
 /**
- * Creates or updates a user profile on behalf of another user.
+ * Activate a user profile.
+ *
+ * Create or update a user profile on behalf of another user.
  * @rest_spec_name security.activate_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private

output/schema/schema.json

@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 
 /**
  * Authenticate a user.
+ *
  * Authenticates a user and returns information about the authenticated user.
  * Include the user information in a [basic auth header](https://en.wikipedia.org/wiki/Basic_access_authentication).
  * A successful call returns a JSON structure that shows user information such as their username, the roles that are assigned to the user, any assigned metadata, and information about the realms that authenticated and authorized the user.

specification/_doc_ids/table.csv

@@ -21,6 +21,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
+ * Bulk delete roles.
+ *
  * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
  * The bulk delete roles API cannot delete roles that are defined in roles files.
  * @rest_spec_name security.bulk_delete_role

specification/security/activate_user_profile/Request.ts

@@ -23,6 +23,8 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
+ * Bulk create or update roles.
+ *
  * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
  * The bulk create or update roles API cannot update roles that are defined in roles files.
  * @rest_spec_name security.bulk_put_role

specification/security/authenticate/SecurityAuthenticateRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Password, Refresh, Username } from '@_types/common'
 
 /**
+ * Change passwords.
+ *
+ * Change the passwords of users in the native realm and built-in users.
  * @rest_spec_name security.change_password
  * @availability stack stability=stable
  */

specification/security/bulk_delete_role/SecurityBulkDeleteRoleRequest.ts

@@ -21,7 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Ids } from '@_types/common'
 
 /**
- * Evicts a subset of all entries from the API key cache.
+ * Clear the API key cache.
+ *
+ * Evict a subset of all entries from the API key cache.
  * The cache is also automatically cleared on state changes of the security index.
  * @rest_spec_name security.clear_api_key_cache
  * @availability stack since=7.10.0 stability=stable

specification/security/bulk_put_role/SecurityBulkPutRoleRequest.ts

@@ -21,6 +21,10 @@ import { RequestBase } from '@_types/Base'
 import { Name } from '@_types/common'
 
 /**
+ * Clear the privileges cache.
+ *
+ * Evict privileges from the native application privilege cache.
+ * The cache is also automatically cleared for applications that have their privileges updated.
  * @rest_spec_name security.clear_cached_privileges
  * @availability stack since=7.9.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/change_password/SecurityChangePasswordRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Clear the user cache.
+ *
+ * Evict users from the user cache. You can completely clear the cache or evict specific users.
  * @rest_spec_name security.clear_cached_realms
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/clear_api_key_cache/SecurityClearApiKeyCacheRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Clear the roles cache.
+ *
+ * Evict roles from the native role cache.
  * @rest_spec_name security.clear_cached_roles
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/clear_cached_privileges/SecurityClearCachedPrivilegesRequest.ts

@@ -21,9 +21,13 @@ import { RequestBase } from '@_types/Base'
 import { Names, Namespace, Service } from '@_types/common'
 
 /**
+ * Clear service account token caches.
+ *
+ * Evict a subset of all entries from the service account token caches.
  * @rest_spec_name security.clear_cached_service_tokens
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/clear_cached_realms/SecurityClearCachedRealmsRequest.ts

@@ -25,7 +25,8 @@ import { Duration } from '@_types/Time'
 
 /**
  * Create an API key.
- * Creates an API key for access without requiring basic authentication.
+ *
+ * Create an API key for access without requiring basic authentication.
  * A successful request returns a JSON structure that contains the API key, its unique id, and its name.
  * If applicable, it also returns expiration information for the API key in milliseconds.
  * NOTE: By default, API keys never expire. You can specify expiration information when you create the API keys.

specification/security/clear_cached_roles/ClearCachedRolesRequest.ts

@@ -21,10 +21,13 @@ import { RequestBase } from '@_types/Base'
 import { Name, Namespace, Refresh, Service } from '@_types/common'
 
 /**
- * Creates a service accounts token for access without requiring basic authentication.
+ * Create a service account token.
+ *
+ * Create a service accounts token for access without requiring basic authentication.
  * @rest_spec_name security.create_service_token
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/clear_cached_service_tokens/ClearCachedServiceTokensRequest.ts

@@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { Name, Names, Refresh } from '@_types/common'
 
 /**
+ * Delete application privileges.
  * @rest_spec_name security.delete_privileges
  * @availability stack since=6.4.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id security-privileges
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/create_api_key/SecurityCreateApiKeyRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Name, Refresh } from '@_types/common'
 
 /**
+ * Delete roles.
+ *
+ * Delete roles in the native realm.
  * @rest_spec_name security.delete_role
  * @availability stack stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/create_service_token/CreateServiceTokenRequest.ts

@@ -21,6 +21,7 @@ import { RequestBase } from '@_types/Base'
 import { Name, Refresh } from '@_types/common'
 
 /**
+ * Delete role mappings.
  * @rest_spec_name security.delete_role_mapping
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/delete_privileges/SecurityDeletePrivilegesRequest.ts

@@ -21,9 +21,13 @@ import { RequestBase } from '@_types/Base'
 import { Name, Namespace, Refresh, Service } from '@_types/common'
 
 /**
+ * Delete service account tokens.
+ *
+ * Delete service account tokens for a service in a specified namespace.
  * @rest_spec_name security.delete_service_token
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/delete_role/SecurityDeleteRoleRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Refresh, Username } from '@_types/common'
 
 /**
+ * Delete users.
+ *
+ * Delete users from the native realm.
  * @rest_spec_name security.delete_user
  * @availability stack stability=stable
  */

specification/security/delete_role_mapping/SecurityDeleteRoleMappingRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Refresh, Username } from '@_types/common'
 
 /**
+ * Disable users.
+ *
+ * Disable users in the native realm.
  * @rest_spec_name security.disable_user
  * @availability stack stability=stable
  */

specification/security/delete_service_token/DeleteServiceTokenRequest.ts

@@ -22,7 +22,9 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
- * Disables a user profile so it's not visible in user profile searches.
+ * Disable a user profile.
+ *
+ * Disable user profiles so that they are not visible in user profile searches.
  * @rest_spec_name security.disable_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/delete_user/SecurityDeleteUserRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Refresh, Username } from '@_types/common'
 
 /**
+ * Enable users.
+ *
+ * Enable users in the native realm.
  * @rest_spec_name security.enable_user
  * @availability stack stability=stable
  */

specification/security/disable_user/SecurityDisableUserRequest.ts

@@ -22,7 +22,9 @@ import { RequestBase } from '@_types/Base'
 import { Refresh } from '@_types/common'
 
 /**
- * Enables a user profile so it's visible in user profile searches.
+ * Enable a user profile.
+ *
+ * Enable user profiles to make them visible in user profile searches.
  * @rest_spec_name security.enable_user_profile
  * @availability stack since=8.2.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/disable_user_profile/Request.ts

@@ -20,7 +20,9 @@
 import { RequestBase } from '@_types/Base'
 
 /**
- * Enables a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.
+ * Enroll Kibana.
+ *
+ * Enable a Kibana instance to configure itself for communication with a secured Elasticsearch cluster.
  * @rest_spec_name security.enroll_kibana
  * @availability stack since=8.0.0 stability=stable
  */

specification/security/enable_user/SecurityEnableUserRequest.ts

@@ -20,7 +20,9 @@
 import { RequestBase } from '@_types/Base'
 
 /**
- * Allows a new node to join an existing cluster with security features enabled.
+ * Enroll a node.
+ *
+ * Enroll a new node to allow it to join an existing cluster with security features enabled.
  * @rest_spec_name security.enroll_node
  * @availability stack since=8.0.0 stability=stable
  */

specification/security/enable_user_profile/Request.ts

@@ -22,6 +22,7 @@ import { Id, Name, Username } from '@_types/common'
 
 /**
  * Get API key information.
+ *
  * Retrieves information for one or more API keys.
  * NOTE: If you have only the `manage_own_api_key` privilege, this API returns only the API keys that you own.
  * If you have `read_security`, `manage_api_key` or greater privileges (including `manage_security`), this API returns all API keys regardless of ownership.

specification/security/enroll_kibana/Request.ts

@@ -20,9 +20,13 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Get builtin privileges.
+ *
+ * Get the list of cluster privileges and index privileges that are available in this version of Elasticsearch.
  * @rest_spec_name security.get_builtin_privileges
  * @availability stack since=7.3.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_security
+ * @ext_doc_id security-privileges
  */
 export interface Request extends RequestBase {}

specification/security/enroll_node/Request.ts

@@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { Name, Names } from '@_types/common'
 
 /**
+ * Get application privileges.
  * @rest_spec_name security.get_privileges
  * @availability stack since=6.4.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id security-privileges
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/get_api_key/SecurityGetApiKeyRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Get roles.
+ *
+ * Get roles in the native realm.
  * The role management APIs are generally the preferred way to manage roles, rather than using file-based role management.
  * The get roles API cannot retrieve roles that are defined in roles files.
  * @rest_spec_name security.get_role

specification/security/get_builtin_privileges/SecurityGetBuiltinPrivilegesRequest.ts

@@ -21,10 +21,16 @@ import { RequestBase } from '@_types/Base'
 import { Names } from '@_types/common'
 
 /**
+ * Get role mappings.
+ *
+ * Role mappings define which roles are assigned to each user.
+ * The role mapping APIs are generally the preferred way to manage role mappings rather than using role mapping files.
+ * The get role mappings API cannot retrieve role mappings that are defined in role mapping files.
  * @rest_spec_name security.get_role_mapping
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_security
+ * @ext_doc_id mapping-roles
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/get_privileges/SecurityGetPrivilegesRequest.ts

@@ -21,11 +21,14 @@ import { RequestBase } from '@_types/Base'
 import { Namespace, Service } from '@_types/common'
 
 /**
- * This API returns a list of service accounts that match the provided path parameter(s).
+ * Get service accounts.
+ *
+ * Get a list of service accounts that match the provided path parameters.
  * @rest_spec_name security.get_service_accounts
  * @availability stack since=7.13.0 stability=stable
  * @availability serverless stability=stable visibility=private
  * @cluster_privileges manage_service_account
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/get_role/SecurityGetRoleRequest.ts

@@ -21,9 +21,11 @@ import { RequestBase } from '@_types/Base'
 import { Name, Namespace } from '@_types/common'
 
 /**
+ * Get service account credentials.
  * @rest_spec_name security.get_service_credentials
  * @availability stack since=7.13.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @ext_doc_id service-accounts
  */
 export interface Request extends RequestBase {
   path_parts: {

specification/security/get_role_mapping/SecurityGetRoleMappingRequest.ts

@@ -23,6 +23,9 @@ import { Password, Username } from '@_types/common'
 import { AccessTokenGrantType } from './types'
 
 /**
+ * Get a token.
+ *
+ * Create a bearer token for access without requiring basic authentication.
  * @rest_spec_name security.get_token
  * @availability stack since=5.5.0 stability=stable
  * @availability serverless stability=stable visibility=private

specification/security/get_service_accounts/GetServiceAccountsRequest.ts

@@ -21,6 +21,9 @@ import { RequestBase } from '@_types/Base'
 import { Username } from '@_types/common'
 
 /**
+ * Get users.
+ *
+ * Get information about users in the native realm and built-in users.
  * @rest_spec_name security.get_user
  * @availability stack stability=stable
  */