OpenAPI: Fix and improve validation, resolve conflicts in endpoint descriptions (#835)

* Attempt to trigger OpenAPI validation at the end of the build

Move invocation to home.navigation.html and set high output format weight, add locks and debug printing for map in arangoproxy

There still appear to be openapi render hook calls after the validation, and Hugo reports the end of the build way before that

* OpenAPI Render Hook: Substitute version alias with version number to prevent duplicate invocations

This is only an issue for endpoint descriptions that contain internal links that get replaced with absolute URLs for api-docs.json / SwaggerUI. Hugo's caching of resources.GetRemote prevents duplicate calls arangoproxy's /openapi if the requests are identical

* Replace invocation of OpenAPI validation

It no longer gets triggered in live builds (hugo server) but only static builds, where we can reliably start the validation after the build

* Add debugging and validation for OpenAPI endpoints to find duplicate operationIds and conflicting endpoint descriptions

Note that identical endpoint descriptions for the same version are not considered an error (used for a few View endpoints on purpose). In fact, Hugo's caching of resources.GetRemote prevents arangoproxy from even getting called twice, which we take advantage of.

* Fix newly discovered conflicts between arangosearch and search-alias View endpoints and operationIds

* Revert addition of output format weight, use single curl HTTP method

arangoproxy's endpoints work with any method (HEAD, POST, ...) but using -I (HEAD) has the advantage that it only returns the HTTP headers

* Propagate validation errors to start_hugo.sh to let the pipeline fail if needed

Also add a temporary bug to an endpoint description for testing

* Propagate spec errors to CI

* Test duplicate operationId

* Remove a required property to cause swagger-cli to fail

* Revert removal of required property

* Reset error booleans

Author: Simran-B

site/content/arangodb/3.11/develop/http-api/views/search-alias-views.md

@@ -211,9 +211,9 @@ db._drop(coll.name());
 
 ```openapi
 paths:
-  /_db/{database-name}/_api/view/{view-name}:
+  /_db/{database-name}/_api/view/{view-name}#searchalias:
     get:
-      operationId: getView
+      operationId: getViewSearchAlias
       description: |
         Returns the basic information about a specific View.
       parameters:
@@ -1012,10 +1012,10 @@ db._drop(coll.name());
 
 ```openapi
 paths:
-  /_db/{database-name}/_api/view/{view-name}/rename:
+  /_db/{database-name}/_api/view/{view-name}/rename#searchalias:
     put:
     # The PATCH method can be used as an alias
-      operationId: renameView
+      operationId: renameViewSearchAlias
       description: |
         Renames a View.
 

site/content/arangodb/3.12/develop/http-api/views/search-alias-views.md

@@ -211,9 +211,9 @@ db._drop(coll.name());
 
 ```openapi
 paths:
-  /_db/{database-name}/_api/view/{view-name}:
+  /_db/{database-name}/_api/view/{view-name}#searchalias:
     get:
-      operationId: getView
+      operationId: getViewSearchAlias
       description: |
         Returns the basic information about a specific View.
       parameters:
@@ -1012,10 +1012,10 @@ db._drop(coll.name());
 
 ```openapi
 paths:
-  /_db/{database-name}/_api/view/{view-name}/rename:
+  /_db/{database-name}/_api/view/{view-name}/rename#searchalias:
     put:
     # The PATCH method can be used as an alias
-      operationId: renameView
+      operationId: renameViewSearchAlias
       description: |
         Renames a View.
 

site/content/arangodb/4.0/develop/http-api/views/search-alias-views.md

@@ -211,9 +211,9 @@ db._drop(coll.name());
 
 ```openapi
 paths:
-  /_db/{database-name}/_api/view/{view-name}:
+  /_db/{database-name}/_api/view/{view-name}#searchalias:
     get:
-      operationId: getView
+      operationId: getViewSearchAlias
       description: |
         Returns the basic information about a specific View.
       parameters:
@@ -1012,10 +1012,10 @@ db._drop(coll.name());
 
 ```openapi
 paths:
-  /_db/{database-name}/_api/view/{view-name}/rename:
+  /_db/{database-name}/_api/view/{view-name}/rename#searchalias:
     put:
     # The PATCH method can be used as an alias
-      operationId: renameView
+      operationId: renameViewSearchAlias
       description: |
         Renames a View.
 

site/themes/arangodb-docs-theme/layouts/_default/_markup/render-codeblock-openapi.html

@@ -8,7 +8,9 @@
   {{- $url := index $match 2 }}
   {{- $isRemote := ne (urls.Parse $url).Scheme "" }}
   {{- if not $isRemote }}
-    {{- $absUrl := printf "https://docs.arango.ai%s" (urls.RelRef $page $url) }}
+    {{- $absPath := urls.RelRef $page $url }}
+    {{- $absPathUnaliased := replaceRE "^/arangodb/(?:stable|devel)/" (printf "/arangodb/%s/" $pageVersion) $absPath 1 }}
+    {{- $absUrl := printf "https://docs.arango.ai%s" $absPathUnaliased }}
     {{- $newLink := printf "[%s](%s)" (index $match 1) $absUrl }}
     {{- $linkMap = merge $linkMap (dict (index $match 0) $newLink) }}
   {{- end }}

site/themes/arangodb-docs-theme/layouts/_default/baseof.html

@@ -29,10 +29,4 @@
     {{ partialCached "back-to-top.html" . -}}
     {{ partialCached "search.html" . -}}
   </body>
-</html>
-{{- /* Trigger validation at the end of the build once */ -}}
-{{ if .IsHome -}}
-  {{ with templates.Defer -}}
-    {{ partial "openapi-validate.html" (dict "key" "global") -}}
-  {{ end -}}
-{{ end -}}
+</html>

site/themes/arangodb-docs-theme/layouts/partials/openapi-validate.html

@@ -127,8 +127,14 @@ func OpenapiHandler(w http.ResponseWriter, r *http.Request) {
 func ValidateOpenapiHandler(w http.ResponseWriter, r *http.Request) {
 	models.Logger.Printf("Validate openapi specs")
 
-	OPENAPIService.ValidateOpenapiGlobalSpec()
+	err := OPENAPIService.ValidateOpenapiGlobalSpec()
 	w.Header().Set("Content-Type", "text/plain") // Any allow-listed media type
+	if err != nil {
+		models.Logger.Printf("[ValidateOpenapiHandler] Validation failed: %s", err.Error())
+		w.WriteHeader(http.StatusInternalServerError)
+		w.Write([]byte(fmt.Sprintf("OpenAPI validation failed: %s", err.Error())))
+		return
+	}
 	w.WriteHeader(http.StatusOK)
 }