Replace OCS API sections with OpenAPI documentation

Signed-off-by: jld3103 <[email protected]>
nextcloud · May 25, 2023 · 0d32040 · 0d32040
1 parent 72400a5
commit 0d32040
Show file tree

Hide file tree

Showing 16 changed files with 57 additions and 975 deletions.
diff --git a/.gitignore b/.gitignore
@@ -29,6 +29,9 @@ _build
 developer_manual/html_css_design/img
 developer_manual/html_css_design/icons.txt
 
+# OpenAPI file
+developer_manual/_static/openapi.json
+
 # Exclude Eclipse project
 .project
 
@@ -47,4 +50,4 @@ venv
 .history/
 
 # JetBrains IDEs
-.idea/
+.idea/
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
@@ -14,7 +14,7 @@ user-manual-html:
 	@echo "User manual build finished; HTML is updated"
 
 # Should also build icons-docs, but due to https://github.com/nextcloud/documentation/issues/7162 it is disabled
-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"
@@ -27,8 +27,15 @@ user-manual-pdf:
 	cd user_manual && make latexpdf
 	@echo "User manual build finished; PDF is updated"
 
-#icons-docs: clean-icons-docs
-#	cd build && sh get-server-sources.sh $(DRONE_BRANCH)
+get-server-sources:
+	cd build && sh get-server-sources.sh $(DRONE_BRANCH)
+
+openapi-spec: get-server-sources
+	git submodule update --init
+	cd build/openapi-extractor && composer install
+	cd build && sh generate-openapi.sh
+
+#icons-docs: clean-icons-docs get-server-sources
 #	cd build && composer install && composer update
 #	cd build && php generateIconsDoc.php
 

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>
diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst
@@ -4,12 +4,14 @@
 OCS API
 ===============================
 
-.. toctree::
-
-   ocs-api-overview
-   ocs-share-api
-   ocs-sharee-api
-   ocs-status-api
-   ocs-recommendations-api
-   ocs-user-preferences-api
-   ocs-translation-api
+To browse the OCS API documentation please go `here <../../_static/openapi.html>`_.
+
+Notifications API
+-----------------
+
+There is also the `Notifications API <https://github.com/nextcloud/notifications/blob/master/docs/ocs-endpoint-v2.md>`_
+
+Activity API
+------------
+
+Find the documentation in the `Activity app repo <https://github.com/nextcloud/activity/blob/master/docs/endpoint-v2.md>`__.
diff --git a/developer_manual/client_apis/OCS/ocs-api-overview.rst b/developer_manual/client_apis/OCS/ocs-api-overview.rst
diff --git a/developer_manual/client_apis/OCS/ocs-recommendations-api.rst b/developer_manual/client_apis/OCS/ocs-recommendations-api.rst