Replace OCS API sections with OpenAPI documentation

Signed-off-by: jld3103 <[email protected]>
nextcloud · May 24, 2023 · 49989b5 · 49989b5
1 parent f4c96a4
commit 49989b5
Show file tree

Hide file tree

Showing 20 changed files with 17,027 additions and 1,194 deletions.
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "build/openapi-extractor"]
+	path = build/openapi-extractor
+	url = https://github.com/nextcloud/openapi-extractor
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,16 @@
+#!/bin/bash
+set -euxo pipefail
+
+./openapi-extractor/merge-specs \
+  --core server/core/openapi.json \
+  --merged ../developer_manual/_static/openapi.json \
+  server/apps/cloud_federation_api/openapi.json \
+  server/apps/dashboard/openapi.json \
+  server/apps/dav/openapi.json \
+  server/apps/files_sharing/openapi.json \
+  server/apps/oauth2/openapi.json \
+  server/apps/provisioning_api/openapi.json \
+  server/apps/settings/openapi.json \
+  server/apps/theming/openapi.json \
+  server/apps/user_status/openapi.json \
+  server/apps/weather_status/openapi.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>