[OpenAPI] Edit SSL certificate API (#3056) (#3069)

(cherry picked from commit e46f571)

Co-authored-by: Lisa Cawley <[email protected]>

docs/overlays/elasticsearch-shared-overlays.yaml

@@ -183,8 +183,6 @@ actions:
           x-displayName: Searchable snapshots
         - name: security
           x-displayName: Security
-        - name: ssl
-          x-displayName: Security - SSL
         - name: snapshot
           x-displayName: Snapshot and restore
           description: >

specification/ssl/certificates/GetCertificatesRequest.ts

@@ -20,8 +20,26 @@
 import { RequestBase } from '@_types/Base'
 
 /**
+ * Get SSL certificates.
+ *
+ * Get information about the X.509 certificates that are used to encrypt communications in the cluster.
+ * The API returns a list that includes certificates from all TLS contexts including:
+ *
+ * - Settings for transport and HTTP interfaces
+ * - TLS settings that are used within authentication realms
+ * - TLS settings for remote monitoring exporters
+ *
+ * The list includes certificates that are used for configuring trust, such as those configured in the `xpack.security.transport.ssl.truststore` and `xpack.security.transport.ssl.certificate_authorities` settings.
+ * It also includes certificates that are used for configuring server identity, such as `xpack.security.http.ssl.keystore` and `xpack.security.http.ssl.certificate settings`.
+ *
+ * The list does not include certificates that are sourced from the default SSL context of the Java Runtime Environment (JRE), even if those certificates are in use within Elasticsearch.
+ *
+ * NOTE: When a PKCS#11 token is configured as the truststore of the JRE, the API returns all the certificates that are included in the PKCS#11 token irrespective of whether these are used in the Elasticsearch TLS configuration.
+ *
+ * If Elasticsearch is configured to use a keystore or truststore, the API output includes all certificates in that store, even though some of the certificates might not be in active use within the cluster.
  * @rest_spec_name ssl.certificates
  * @availability stack since=6.2.0 stability=stable
  * @availability serverless stability=stable visibility=private
+ * @doc_tag security
  */
 export interface Request extends RequestBase {}