Merge remote-tracking branch 'origin/main' into remove-block-api

Author: pquentin

.gitignore

@@ -65,10 +65,7 @@ output/schema/schema
 # Test suite outputs
 compiler/test/**/output/
 
-# Temporary openAPI files
-output/openapi/elasticsearch-serverless-openapi.tmp*.json
-output/openapi/elasticsearch-serverless-openapi.examples.json
-output/openapi/elasticsearch-openapi.tmp*.json
-output/openapi/elasticsearch-openapi.examples.json
-output/openapi/elasticsearch-serverless-openapi-docs.json
-output/openapi/elasticsearch-openapi-docs.json
+# Temporary openAPI documentation files
+output/openapi/elasticsearch-serverless-openapi-docs*.json
+output/openapi/elasticsearch-openapi-docs*.json
+output/openapi/elasticsearch*.redirects.csv

CONTRIBUTING.md

@@ -39,7 +39,7 @@ Documents under the docs/ directory will help you to change the specification. T
  * [Fixing a definition, the complete story](docs/validation-example.md)
 
 
-## Send your pull request
+## Send your pull request from a branch
 
 To fix any style issues and generate the outputs (that we store in git), please run:
 
@@ -56,5 +56,4 @@ Then, follow those steps:
   - If the API is unusable without the change -> every supported version
   - If the API is usable, but fix is on the response side -> every supported version
   - If the API is usable, but fix is on the request side -> no backport, unless the API is _partially_ usable and the fix unlocks a missing feature that has no workaround
-
-
+- Send the pull request from a branch, **not a fork**

Makefile

@@ -69,14 +69,14 @@ dump-routes: ## Create a new schema with all generics expanded
 	@npm run dump-routes --prefix compiler
 
 overlay-docs: ## Apply overlays to OpenAPI documents
-	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp1.json"
-	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi.tmp2.json"
-	@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi.examples.json
-	@npx bump overlay "output/openapi/elasticsearch-openapi.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp1.json"
-	@npx bump overlay "output/openapi/elasticsearch-openapi.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-openapi.tmp2.json"
-	@npx @redocly/cli bundle output/openapi/elasticsearch-openapi.tmp2.json --ext json -o output/openapi/elasticsearch-openapi.examples.json
-	rm output/openapi/elasticsearch-serverless-openapi.tmp*.json
-	rm output/openapi/elasticsearch-openapi.tmp*.json
+	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi-docs.json" "docs/overlays/elasticsearch-serverless-openapi-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi-docs.tmp1.json"
+	@npx bump overlay "output/openapi/elasticsearch-serverless-openapi-docs.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-serverless-openapi-docs.tmp2.json"
+	@npx @redocly/cli bundle output/openapi/elasticsearch-serverless-openapi-docs.tmp2.json --ext json -o output/openapi/elasticsearch-serverless-openapi-docs-final.json
+	@npx bump overlay "output/openapi/elasticsearch-openapi-docs.json" "docs/overlays/elasticsearch-openapi-overlays.yaml" > "output/openapi/elasticsearch-openapi-docs.tmp1.json"
+	@npx bump overlay "output/openapi/elasticsearch-openapi-docs.tmp1.json" "docs/overlays/elasticsearch-shared-overlays.yaml" > "output/openapi/elasticsearch-openapi-docs.tmp2.json"
+	@npx @redocly/cli bundle output/openapi/elasticsearch-openapi-docs.tmp2.json --ext json -o output/openapi/elasticsearch-openapi-docs-final.json
+	rm output/openapi/elasticsearch-serverless-openapi-docs.tmp*.json
+	rm output/openapi/elasticsearch-openapi-docs.tmp*.json
 
 generate-language-examples:
 	@node docs/examples/generate-language-examples.js
@@ -89,11 +89,11 @@ generate-language-examples-with-java:
 lint-docs: ## Lint the OpenAPI documents after overlays
 	@npx @redocly/cli lint "output/openapi/elasticsearch-*.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
-lint-docs-stateful: ## Lint only the elasticsearch-openapi.examples.json file
-	@npx @redocly/cli lint "output/openapi/elasticsearch-openapi.examples.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
+lint-docs-stateful: ## Lint only the elasticsearch-openapi-docs-final.json file
+	@npx @redocly/cli lint "output/openapi/elasticsearch-openapi-docs-final.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
 lint-docs-serverless: ## Lint only the serverless OpenAPI document after overlays
-	@npx @redocly/cli lint "output/openapi/elasticsearch-serverless-openapi.examples.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
+	@npx @redocly/cli lint "output/openapi/elasticsearch-serverless-openapi-docs-final.json" --config "docs/linters/redocly.yaml" --format stylish --max-problems 500
 
 contrib: | generate license-check spec-format-fix transform-to-openapi filter-for-serverless lint-docs ## Pre contribution target
 

README.md

@@ -250,7 +250,7 @@ If you need to download the recordings again, run `make validate-no-cache api=xp
 
 Once you see the errors, you can fix the original definition in `/specification`
 and then run the command again until the types validator does not trigger any new error.
-Finally open a pull request with your changes.
+Finally open a pull request with your changes. Please open it from a branch in the repository, and not from a fork.
 
 ## Documentation
 

compiler-rs/clients_schema/src/lib.rs

@@ -1003,7 +1003,6 @@ pub struct UrlTemplate {
 pub struct ModelInfo {
     pub title: String,
     pub license: License,
-    pub version: Option<String>,
 }
 
 #[derive(Debug, Clone, Serialize, Deserialize)]

compiler-rs/clients_schema_to_openapi/src/cli.rs

@@ -24,6 +24,10 @@ pub struct Cli {
     #[argh(option)]
     pub namespace: Vec<String>,
 
+    /// the branch to generate [9.0, 8.19, current, etc... - default = current]
+    #[argh(option)]
+    pub branch: Option<String>,
+
     /// add enum descriptions to property descriptions [default = true]
     #[argh(switch)]
     pub lift_enum_descriptions: bool,
@@ -72,9 +76,12 @@ impl From<Cli> for Configuration {
             SchemaFlavor::Serverless => Some(Flavor::Serverless),
             SchemaFlavor::Stack => Some(Flavor::Stack),
         };
+        
+        let branch = cli.branch;
 
         Configuration {
             flavor,
+            branch,
             lift_enum_descriptions: cli.lift_enum_descriptions,
             merge_multipath_endpoints: cli.merge_multipath_endpoints,
             multipath_redirects: cli.multipath_redirects,

compiler-rs/clients_schema_to_openapi/src/lib.rs

@@ -32,6 +32,7 @@ use crate::components::TypesAndComponents;
 pub struct Configuration {
     pub flavor: Option<Flavor>,
     pub namespaces: Option<Vec<String>>,
+    pub branch: Option<String>,
 
     /// If a property value is an enumeration, the description of possible values will be copied in the
     /// property's description (also works for arrays of enums).

compiler-rs/clients_schema_to_openapi/src/schemas.rs

@@ -209,19 +209,14 @@ impl<'a> TypesAndComponents<'a> {
     pub fn convert_external_docs(&self, obj: &impl clients_schema::ExternalDocument) -> Option<ExternalDocumentation> {
         // FIXME: does the model contain resolved doc_id?
         obj.ext_doc_url().map(|url| {
-            let branch: &str = self
-                .model
-                .info
-                .as_ref()
-                .and_then(|i| i.version.as_deref())
-                .unwrap_or("current");
+            let branch = self.config.branch.clone();
             let mut extensions: IndexMap<String,serde_json::Value> = Default::default();
             if let Some(previous_version_doc_url) = obj.ext_previous_version_doc_url() {
                 extensions.insert("x-previousVersionUrl".to_string(), serde_json::json!(previous_version_doc_url));
             }
             ExternalDocumentation {
                 description: None,
-                url: url.trim().replace("{branch}", branch),
+                url: url.trim().replace("{branch}", &branch.unwrap_or("current".to_string())),
                 extensions,
             }
         })