Add new OCS API documentation

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

Hide file tree

Showing 7 changed files with 50 additions and 4 deletions.
diff --git a/.gitignore b/.gitignore
@@ -29,6 +29,11 @@ _build
 developer_manual/html_css_design/img
 developer_manual/html_css_design/icons.txt
 
+# OpenAPI file
+developer_manual/_static/openapi.json
+developer_manual/_static/stoplight-elements.js
+developer_manual/_static/stoplight-elements.css
+
 # Exclude Eclipse project
 .project
 
@@ -47,4 +52,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
@@ -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,8 +26,31 @@ 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)
+
+openapi-spec: get-server-sources
+	git submodule update --init
+	cd build/openapi-extractor && composer install
+	cd build && ./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
+	cd developer_manual/_static && \
+		wget https://unpkg.com/@stoplight/[email protected]/web-components.min.js -O stoplight-elements.js && \
+		wget https://unpkg.com/@stoplight/[email protected]/styles.min.css -O stoplight-elements.css
+
+
+icons-docs: clean-icons-docs get-server-sources
 	cd build && composer install && composer update
 	cd build && php generateIconsDoc.php
 

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="stoplight-elements.js"></script>
+        <link rel="stylesheet" href="stoplight-elements.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,6 +4,10 @@
 OCS API
 ===============================
 
+To browse the new OCS API documentation please go `here <../../_static/openapi.html>`_.
+
+The old documentation is still kept as it provides some additional documentation that is not completely covered in the new documentation:
+
 .. toctree::
 
    ocs-api-overview

diff --git a/developer_manual/conf.py b/developer_manual/conf.py
@@ -126,7 +126,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['../_shared_assets/static']
+html_static_path = ['../_shared_assets/static', '_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.