Add examples to licensing APIs (#3420)

Co-authored-by: István Zoltán Szabó <[email protected]> (cherry picked from commit e153632)
elastic · Jan 3, 2025 · 96fc5a5 · 96fc5a5
1 parent e9b082d
commit 96fc5a5
Show file tree

Hide file tree

Showing 11 changed files with 135 additions and 7 deletions.
diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml
@@ -392,6 +392,63 @@ actions:
           examples:
             indicesLegacyPutTemplateRequestExample1:
               $ref: "../../specification/indices/put_template/indicesPutTemplateRequestExample1.yaml"
+## Examples for licensing
+  - target: "$.paths['/_license/basic_status']['get']"
+    description: "Add example for get basic status response"
+    update: 
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                getBasicStatusResponseExample1:
+                  $ref: "../../specification/license/get_basic_status/GetBasicLicenseStatusResponseExample1.yaml"
+  - target: "$.paths['/_license/trial_status']['get']"
+    description: "Add example for get trial status response"
+    update: 
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                getLicenseResponseExample1:
+                  $ref: "../../specification/license/get_trial_status/GetTrialLicenseStatusResponseExample1.yaml"
+  - target: "$.paths['/_license/start_basic']['post']"
+    description: "Add example for start basic response"
+    update: 
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                startBasicLicenseResponseExample1:
+                  $ref: "../../specification/license/post_start_basic/StartBasicLicenseResponseExample1.yaml"
+  - target: "$.paths['/_license/start_trial']['post']"
+    description: "Add example for start trial response"
+    update: 
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                startTrialLicenseResponseExample1:
+                  $ref: "../../specification/license/post_start_trial/StartTrialLicenseResponseExample1.yaml"
+  - target: "$.components['requestBodies']['license.post']"
+    description: "Add examples for update license request"
+    update: 
+      content: 
+        application/json: 
+          examples: 
+            updateLicenseRequestExample1: 
+              $ref: "../../specification/license/post/PostLicenseRequestExample1.yaml"
+  - target: "$.components['responses']['license.post#200']"
+    description: "Add examples for update license response"
+    update: 
+      content:
+        application/json:
+          examples:
+            clusterHealthResponseExample1:
+              $ref: "../../specification/license/post/PostLicenseResponseExample1.yaml"
 ## Examples for search applications
   - target: "$.paths['/_application/search_application/{name}/_render_query']['post']"
     description: "Add examples for render search application query operation"
@@ -402,10 +459,5 @@ actions:
             examples:
               renderSearchApplicationQueryRequestExample1: 
                 $ref: "../../specification/search_application/render_query/SearchApplicationsRenderQueryRequestExample1.yaml"
-      responses:
-        200:
-          content:
-            application/json:
-              examples:
                 renderSearchApplicationQueryResponseExample1:
                   $ref: "../../specification/search_application/render_query/SearchApplicationsRenderQueryResponseExample1.yaml"
diff --git a/docs/overlays/elasticsearch-shared-overlays.yaml b/docs/overlays/elasticsearch-shared-overlays.yaml
@@ -1351,3 +1351,14 @@ actions:
           examples:
             indicesRolloverResponseExample1:
               $ref: "../../specification/indices/rollover/indicesRolloverResponseExample1.yaml"
+## Examples for licensing
+  - target: "$.paths['/_license']['get']"
+    description: "Add example for get license response"
+    update: 
+      responses:
+        200:
+          content:
+            application/json:
+              examples:
+                getLicenseResponseExample1:
+                  $ref: "../../specification/license/get/GetLicenseResponseExample1.yaml"
diff --git a/output/schema/schema.json b/output/schema/schema.json
diff --git a/specification/license/get/GetLicenseResponseExample1.yaml b/specification/license/get/GetLicenseResponseExample1.yaml
@@ -0,0 +1,11 @@
+# summary: licensing/get-license.asciidoc:61
+description: A successful response from `GET /_license`.
+# type: response
+# response_code: ''
+value:
+  "{\n  \"license\" : {\n    \"status\" : \"active\",\n    \"uid\" : \"cbff45e7-c553-41f7-ae4f-9205eabd80xx\"\
+  ,\n    \"type\" : \"trial\",\n    \"issue_date\" : \"2018-10-20T22:05:12.332Z\"\
+  ,\n    \"issue_date_in_millis\" : 1540073112332,\n    \"expiry_date\" : \"2018-11-19T22:05:12.332Z\"\
+  ,\n    \"expiry_date_in_millis\" : 1542665112332,\n    \"max_nodes\" : 1000,\n \
+  \   \"max_resource_units\" : null,\n    \"issued_to\" : \"test\",\n    \"issuer\"\
+  \ : \"elasticsearch\",\n    \"start_date_in_millis\" : -1\n  }\n}"
diff --git a/specification/license/get_basic_status/GetBasicLicenseStatusResponseExample1.yaml b/specification/license/get_basic_status/GetBasicLicenseStatusResponseExample1.yaml
@@ -0,0 +1,6 @@
+# summary: licensing/get-basic-status.asciidoc:42
+description: A successful response from `GET /_license/basic_status`.
+# type: response
+# response_code: 200
+value:
+  eligible_to_start_basic: true
diff --git a/specification/license/get_trial_status/GetTrialLicenseStatusResponseExample1.yaml b/specification/license/get_trial_status/GetTrialLicenseStatusResponseExample1.yaml
@@ -0,0 +1,6 @@
+# summary: licensing/get-trial-status.asciidoc:47
+description: A successful response from `GET /_license/trial_status`.
+# type: response
+# response_code: 200
+value:
+  eligible_to_start_trial: true
diff --git a/specification/license/post/PostLicenseRequestExample1.yaml b/specification/license/post/PostLicenseRequestExample1.yaml
@@ -0,0 +1,11 @@
+# summary: licensing/update-license.asciidoc:63
+# method_request: PUT _license
+description: >
+  Run `PUT _license` to update to a basic license. NOTE: These values are invalid; you must substitute the appropriate contents from your license file.
+# type: request
+value:
+  "{\n  \"licenses\": [\n    {\n      \"uid\":\"893361dc-9749-4997-93cb-802e3d7fa4xx\"\
+  ,\n      \"type\":\"basic\",\n      \"issue_date_in_millis\":1411948800000,\n  \
+  \    \"expiry_date_in_millis\":1914278399999,\n      \"max_nodes\":1,\n      \"\
+  issued_to\":\"issuedTo\",\n      \"issuer\":\"issuer\",\n      \"signature\":\"\
+  xx\"\n    }\n    ]\n}"
diff --git a/specification/license/post/PostLicenseResponseExample1.yaml b/specification/license/post/PostLicenseResponseExample1.yaml
@@ -0,0 +1,15 @@
+# summary: licensing/get-trial-status.asciidoc:47
+description: If you update to a basic license and you previously had a license with more features, you receive this type of response. You must re-submit the API request and set the `acknowledge` parameter to `true`.
+# type: response
+# response_code: 200
+value:
+  acknowledged: false
+  license_status: valid
+  acknowledge:
+    message: '"""This license update requires acknowledgement. To acknowledge the license, please read the following messages and update the license again, this time with the "acknowledge=true" parameter:"""'
+    watcher:
+      - Watcher will be disabled
+    logstash:
+      - Logstash will no longer poll for centrally-managed pipelines
+    security:
+      - The following X-Pack security functionality will be disabled ...
diff --git a/specification/license/post_start_basic/StartBasicLicenseResponseExample1.yaml b/specification/license/post_start_basic/StartBasicLicenseResponseExample1.yaml
@@ -0,0 +1,7 @@
+# summary:
+description: A successful response from `POST /_license/start_basic?acknowledge=true`. If you currently have a license with more features than a basic license and you start a basic license, you must pass the acknowledge parameter.
+# type: response
+# response_code: 200
+value:
+  basic_was_started: true
+  acknowledged: true
diff --git a/specification/license/post_start_trial/StartTrialLicenseRequest.ts b/specification/license/post_start_trial/StartTrialLicenseRequest.ts
@@ -30,6 +30,7 @@ import { RequestBase } from '@_types/Base'
  * @rest_spec_name license.post_start_trial
  * @availability stack since=6.1.0 stability=stable
  * @cluster_privileges manage
+ * @doc_id start-trial
  */
 export interface Request extends RequestBase {
   query_parameters: {

diff --git a/specification/license/post_start_trial/StartTrialLicenseResponseExample1.yaml b/specification/license/post_start_trial/StartTrialLicenseResponseExample1.yaml
@@ -0,0 +1,7 @@
+# summary:
+description: A successful response from `POST /_license/start_trial?acknowledge=true`.
+# type: response
+# response_code: 200
+value:
+  trial_was_started: true
+  acknowledged: true