Skip to content

Commit f8856c7

Browse files
lcawllcawl
authored
Add examples to both OpenAPI documents via overlays (#2882)
1 parent c982446 commit f8856c7

5 files changed

+114
-71
lines changed

‎.gitignore

+4-2
Original file line numberDiff line numberDiff line change
@@ -66,5 +66,7 @@ output/schema/schema
6666
compiler/test/**/output/
6767

6868
# Temporary openAPI files
69-
output/openapi/elasticsearch-serverless-openapi.tmp.json
70-
output/openapi/elasticsearch-serverless-openapi.examples.json
69+
output/openapi/elasticsearch-serverless-openapi.tmp*.json
70+
output/openapi/elasticsearch-serverless-openapi.examples.json
71+
output/openapi/elasticsearch-openapi.tmp*.json
72+
output/openapi/elasticsearch-openapi.examples.json

‎Makefile

+11-3
Original file line numberDiff line numberDiff line change
@@ -60,13 +60,21 @@ dump-routes: ## Create a new schema with all generics expanded
6060
contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless ## Pre contribution target
6161

6262
overlay-docs: ## Apply overlays to OpenAPI documents
63-
@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp.json"
64-
@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json
65-
rm output/openapi/elasticsearch-serverless-openapi.tmp.json
63+
@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp1.json"
64+
@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-example-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp2.json"
65+
@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json
66+
@npx bump overlay "output/openapi/elasticsearch-openapi.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp1.json"
67+
@npx bump overlay "output/openapi/elasticsearch-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-example-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp2.json"
68+
@npx @redocly/cli bundle output/openapi/elasticsearch-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-openapi.examples.json
69+
rm output/openapi/elasticsearch-serverless-openapi.tmp*.json
70+
rm output/openapi/elasticsearch-openapi.tmp*.json
6671

6772
lint-docs: ## Lint the OpenAPI documents
6873
@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml
6974

75+
lint-docs-errs: ## Lint the OpenAPI documents and return only errors
76+
@npx @stoplight/spectral-cli lint output/openapi/*.json --ruleset .spectral.yaml -D
77+
7078
lint-docs-serverless: ## Lint only the serverless OpenAPI document
7179
@npx @stoplight/spectral-cli lint output/openapi/elasticsearch-serverless-openapi.json --ruleset .spectral.yaml
7280

‎docs/overlays/elasticsearch-openapi-overlays.yaml

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# overlays.yaml
2+
overlay: 1.0.0
3+
info:
4+
title: Overlays for the Elasticsearch OpenAPI document
5+
version: 0.0.1
6+
actions:
7+
- target: '$.info'
8+
description: Add a document description and feedback link
9+
update:
10+
title: Elasticsearch API
11+
description: >
12+
## Documentation source and versions
13+
14+
This documentation is derived from the `main` branch of the [elasticsearch-specification](https://github.com/elastic/elasticsearch-specification) repository.
15+
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
16+
x-doc-license:
17+
name: Attribution-NonCommercial-NoDerivatives 4.0 International
18+
url: 'https://creativecommons.org/licenses/by-nc-nd/4.0/'
19+
x-feedbackLink:
20+
label: Feedback
21+
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+

‎docs/overlays/elasticsearch-serverless-openapi-overlays.yaml

+6-66
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ actions:
77
- target: '$.info'
88
description: Add a document description and feedback link
99
update:
10+
title: Elasticsearch Serverless API
1011
description: >
1112
**Technical preview**
1213
This functionality is in technical preview and may be changed or removed in a future release.
@@ -22,69 +23,8 @@ actions:
2223
x-feedbackLink:
2324
label: Feedback
2425
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
25-
- target: "$.components['requestBodies']['async_search.submit']"
26-
description: "Add example for asynch search submit request"
27-
update:
28-
content:
29-
application/json:
30-
examples:
31-
asyncSearchSubmitResponseExample1:
32-
$ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json"
33-
- target: "$.components['responses']['async_search.submit#200']"
34-
description: "Add example for asynch search submit response"
35-
update:
36-
content:
37-
application/json:
38-
examples:
39-
asyncSearchSubmitResponseExample1:
40-
$ref: "../../specification/async_search/submit/AsyncSearchSubmitResponseExample1.json"
41-
- target: "$.paths['/_transform/{transform_id}']['put']"
42-
description: "Add examples for create transform operation"
43-
update:
44-
requestBody:
45-
content:
46-
application/json:
47-
examples:
48-
createTransformRequestExample1:
49-
$ref: "../../specification/transform/put_transform/PutTransformRequestExample1.json"
50-
createTransformRequestExample2:
51-
$ref: "../../specification/transform/put_transform/PutTransformRequestExample2.json"
52-
responses:
53-
200:
54-
content:
55-
application/json:
56-
examples:
57-
createTransformResponseExample1:
58-
$ref: "../../specification/transform/put_transform/PutTransformResponseExample1.json"
59-
- target: "$.components['requestBodies']['transform.preview_transform']"
60-
description: "Add examples for preview transform operation"
61-
update:
62-
content:
63-
application/json:
64-
examples:
65-
previewTransformRequestExample1:
66-
$ref: "../../specification/transform/preview_transform/PreviewTransformRequestExample1.json"
67-
- target: "$.components['reponses']['transform.preview_transform#200']"
68-
description: "Add examples for preview transform operation"
69-
update:
70-
content:
71-
application/json:
72-
examples:
73-
previewTransformResponseExample1:
74-
$ref: "../../specification/transform/preview_transform/PreviewTransformResponseExample1.json"
75-
- target: "$.paths['/_transform/{transform_id}/_update']['post']"
76-
description: "Add examples for update transform operation"
77-
update:
78-
requestBody:
79-
content:
80-
application/json:
81-
examples:
82-
updateTransformRequestExample1:
83-
$ref: "../../specification/transform/update_transform/UpdateTransformRequestExample1.json"
84-
responses:
85-
200:
86-
content:
87-
application/json:
88-
examples:
89-
updateTransformResponseExample1:
90-
$ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json"
26+
# Temporarily mark all operations as beta
27+
- target: "$.paths[*]['get','put','post','delete','options','head','patch','trace']"
28+
description: Add x-beta
29+
update:
30+
x-beta: true

‎docs/overlays/elasticsearch-shared-example-overlays.yaml

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# overlays.yaml
2+
overlay: 1.0.0
3+
info:
4+
title: Overlays for examples that apply to both Elasticsearcb and Elasticsearch Serverless OpenAPI documents
5+
version: 0.0.1
6+
actions:
7+
- target: "$.components['requestBodies']['async_search.submit']"
8+
description: "Add example for asynch search submit request"
9+
update:
10+
content:
11+
application/json:
12+
examples:
13+
asyncSearchSubmitResponseExample1:
14+
$ref: "../../specification/async_search/submit/AsyncSearchSubmitRequestExample1.json"
15+
- target: "$.components['responses']['async_search.submit#200']"
16+
description: "Add example for asynch search submit response"
17+
update:
18+
content:
19+
application/json:
20+
examples:
21+
asyncSearchSubmitResponseExample1:
22+
$ref: "../../specification/async_search/submit/AsyncSearchSubmitResponseExample1.json"
23+
- target: "$.paths['/_transform/{transform_id}']['put']"
24+
description: "Add examples for create transform operation"
25+
update:
26+
requestBody:
27+
content:
28+
application/json:
29+
examples:
30+
createTransformRequestExample1:
31+
$ref: "../../specification/transform/put_transform/PutTransformRequestExample1.json"
32+
createTransformRequestExample2:
33+
$ref: "../../specification/transform/put_transform/PutTransformRequestExample2.json"
34+
responses:
35+
200:
36+
content:
37+
application/json:
38+
examples:
39+
createTransformResponseExample1:
40+
$ref: "../../specification/transform/put_transform/PutTransformResponseExample1.json"
41+
- target: "$.components['requestBodies']['transform.preview_transform']"
42+
description: "Add examples for preview transform operation"
43+
update:
44+
content:
45+
application/json:
46+
examples:
47+
previewTransformRequestExample1:
48+
$ref: "../../specification/transform/preview_transform/PreviewTransformRequestExample1.json"
49+
- target: "$.components['reponses']['transform.preview_transform#200']"
50+
description: "Add examples for preview transform operation"
51+
update:
52+
content:
53+
application/json:
54+
examples:
55+
previewTransformResponseExample1:
56+
$ref: "../../specification/transform/preview_transform/PreviewTransformResponseExample1.json"
57+
- target: "$.paths['/_transform/{transform_id}/_update']['post']"
58+
description: "Add examples for update transform operation"
59+
update:
60+
requestBody:
61+
content:
62+
application/json:
63+
examples:
64+
updateTransformRequestExample1:
65+
$ref: "../../specification/transform/update_transform/UpdateTransformRequestExample1.json"
66+
responses:
67+
200:
68+
content:
69+
application/json:
70+
examples:
71+
updateTransformResponseExample1:
72+
$ref: "../../specification/transform/update_transform/UpdateTransformResponseExample1.json"

0 commit comments

Comments
 (0)