Add new OCS API documentation

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

Hide file tree

Showing 9 changed files with 49 additions and 5 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
@@ -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,15 @@ 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 && 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,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.

diff --git a/developer_manual/digging_deeper/translation.rst b/developer_manual/digging_deeper/translation.rst
@@ -18,7 +18,7 @@ To consume the Translation API, you will need to :ref:`inject<dependency-injecti
  * ``translate(string $text, ?string $fromLanguage, string $toLanguage)`` This method provides the actual translation functionality. Note that, depending on the length of the text you want to translate, this may take longer than the HTTP request timeout or the PHP execution time limit.
  * ``canDetectLanguage()`` This method returns a boolean indicating whether language auto-detection is possible. If this is true, you can pass ``null`` as a ``$fromLanguage`` parameter to ``translate`` and it will automatically figure out the source language.
 
-If you would like to use the translation functionality in a client, there are also OCS endpoints available for this: :ref:`OCS Translation API<ocs-translation-api>`
+If you would like to use the translation functionality in a client, there are also OCS endpoints available for this: :ref:`OCS Translation API<ocsapiindex>`
 
 Implementing a Translation provider
 -----------------------------------