Replace OCS API sections with OpenAPI documentation

Signed-off-by: jld3103 <[email protected]>
nextcloud · Apr 14, 2023 · 41ce5ab · 41ce5ab
1 parent 1a4c0bb
commit 41ce5ab
Show file tree

Hide file tree

Showing 18 changed files with 16,556 additions and 1,082 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "build/openapi-extractor"]
+	path = build/openapi-extractor
+	url = [email protected]:nextcloud-gmbh/openapi-extractor.git
diff --git a/Makefile b/Makefile
@@ -13,7 +13,7 @@ user-manual-html:
 	cd user_manual && make html
 	@echo "User manual build finished; HTML is updated"
 
-developer-manual-html: icons-docs
+developer-manual-html: openapi-spec icons-docs
 	rm -rf developer_manual/_build/html/com
 	cd developer_manual && make html
 	@echo "Developer manual build finished; HTML is updated"
@@ -26,11 +26,17 @@ user-manual-pdf:
 	cd user_manual && make latexpdf
 	@echo "User manual build finished; PDF is updated"
 
-icons-docs: clean-icons-docs
+get-server-sources:
 	cd build && sh get-server-sources.sh $(DRONE_BRANCH)
+
+icons-docs: clean-icons-docs get-server-sources
 	cd build && composer install && composer update
 	cd build && php generateIconsDoc.php
 
+openapi-spec: get-server-sources
+	cd build/openapi-extractor && composer install
+	cd build && sh generate-openapi.sh
+
 clean: clean-icons-docs
 	rm -r admin_manual/_build developer_manual/_build user_manual/_build user_manual_de_/_build
 

diff --git a/build/.gitignore b/build/.gitignore
@@ -0,0 +1 @@
+/specs/
diff --git a/build/generate-openapi.sh b/build/generate-openapi.sh
@@ -0,0 +1,21 @@
+#!/bin/bash
+set -euxo pipefail
+
+mkdir -p specs
+for path in core apps/cloud_federation_api apps/dashboard apps/dav apps/files_sharing apps/oauth2 apps/provisioning_api apps/settings apps/theming apps/user_status apps/weather_status; do
+  ./openapi-extractor/openapi-extractor "server/$path" "specs/$(echo $path | rev | cut -d "/" -f -1 | rev).json"
+done
+
+./openapi-extractor/merge-specs \
+  --core specs/core.json \
+  --merged ../developer_manual/_static/openapi.json \
+  specs/cloud_federation_api.json \
+  specs/dashboard.json \
+  specs/dav.json \
+  specs/files_sharing.json \
+  specs/oauth2.json \
+  specs/provisioning_api.json \
+  specs/settings.json \
+  specs/theming.json \
+  specs/user_status.json \
+  specs/weather_status.json
diff --git a/build/openapi-extractor b/build/openapi-extractor
diff --git a/developer_manual/_static/openapi.html b/developer_manual/_static/openapi.html
@@ -0,0 +1,10 @@
+<html>
+    <head>
+        <title>OCS API</title>
+        <script src="https://unpkg.com/@stoplight/elements/web-components.min.js"></script>
+        <link rel="stylesheet" href="https://unpkg.com/@stoplight/elements/styles.min.css">
+    </head>
+    <body>
+        <elements-api apiDescriptionUrl="openapi.json" router="hash" hideTryIt="true" logo="logo-blue.png"></elements-api>
+    </body>
+</html>