Fix docs OpenAPI spec generation for render_swagger compatibility (#3729)

Replace mkdocs_gen_files.open() with direct file writes so that
render_swagger can find the JSON files on the real filesystem.
Also fix the rest plugin output path (rest_plugin/ -> rest/) and
remove the committed openapi.json in favor of always generating it.
Skip writing when content is unchanged to avoid livereload loops.

Fixes #3724
Fixes #3725

Co-authored-by: Andrey Cheptsov <andrey.cheptsov@github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -27,3 +27,4 @@ uv.lock
 
 profiling_results.html
 docs/docs/reference/api/rest/openapi.json
+docs/docs/reference/plugins/rest/rest_plugin_openapi.json

docs/docs/reference/api/rest/openapi.json

@@ -3,8 +3,7 @@
 """
 
 import json
-
-import mkdocs_gen_files
+from pathlib import Path
 
 from dstack._internal.server.main import app
 from dstack._internal.settings import DSTACK_VERSION
@@ -15,5 +14,8 @@
     {"url": "https://sky.dstack.ai", "description": "Managed server"},
 ]
 app.version = DSTACK_VERSION or "0.0.0"
-with mkdocs_gen_files.open("docs/reference/api/rest/openapi.json", "w") as f:
-    json.dump(app.openapi(), f)
+output_path = Path("docs/docs/reference/api/rest/openapi.json")
+output_path.parent.mkdir(parents=True, exist_ok=True)
+new_content = json.dumps(app.openapi())
+if not output_path.exists() or output_path.read_text() != new_content:
+    output_path.write_text(new_content)

scripts/docs/gen_openapi_reference.py

@@ -4,8 +4,7 @@
 
 import json
 import logging
-
-import mkdocs_gen_files
+from pathlib import Path
 
 from dstack._internal.settings import DSTACK_VERSION
 
@@ -26,7 +25,8 @@
     {"url": "http://localhost:8000", "description": "Local server"},
 ]
 app.version = DSTACK_VERSION or "0.0.0"
-with mkdocs_gen_files.open(
-    "docs/reference/plugins/rest_plugin/rest_plugin_openapi.json", "w"
-) as f:
-    json.dump(app.openapi(), f)
+output_path = Path("docs/docs/reference/plugins/rest/rest_plugin_openapi.json")
+output_path.parent.mkdir(parents=True, exist_ok=True)
+new_content = json.dumps(app.openapi())
+if not output_path.exists() or output_path.read_text() != new_content:
+    output_path.write_text(new_content)