chore(docs): add API documentation (#98)

Ability to; 1. Generate API document 2. Serve API documentation using mkdocs Closes #97
ametnes · May 27, 2024 · 12c2633 · 12c2633
1 parent 7a74799
commit 12c2633
Show file tree

Hide file tree

Showing 25 changed files with 2,517 additions and 24 deletions.
diff --git a/Makefile b/Makefile
@@ -0,0 +1,4 @@
+.PHONY: all
+
+swagger:
+	python nesis/api/spec/main.py --destination="docs/src/apps/swagger.yaml"
diff --git a/docs/README.md b/docs/README.md
@@ -15,3 +15,11 @@ We use mkdocs to create Nesis documentation.
     mkdocs serve
     ```
 3. The documentation should now be reachable at [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
+
+
+## Generating Swagger documentation
+At the root of the repository, run
+
+```commandline
+make swagger
+```
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -31,6 +31,8 @@ markdown_extensions:
   - attr_list
   - admonition
   - pymdownx.details
+  - pymdownx.tabbed:
+      alternate_style: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -44,7 +46,9 @@ nav:
       - 'installing/helm.md'
       - 'installing/ametnes.md'
   - 'Access Control': 'rbac.md'
-  - 'App Integration': 'apps/example.ipynb'
+  - 'App Integration':
+      - 'API Reference': 'apps/swagger.md'
+      - 'Example': 'apps/example.ipynb'
   - 'Single Sign On':
       - 'sso/azure.md'
   - 'Development Guide':
@@ -54,8 +58,13 @@ nav:
 
 plugins:
   - mkdocs-jupyter
+  - search
+  - neoteroi.mkdocsoad:
+      use_pymdownx: true
 
 extra_css:
     - css/extra.css
+    - css/mkdocsoad.css
+
 extra_javascript:
   - scripts/menus.js
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,3 +4,9 @@ mkdocs-material==9.0.5
 mkdocs-bootstrap==1.1
 mkdocs-bootswatch==1.1
 mkdocs-jupyter==0.24.7
+neoteroi-mkdocs==1.0.5
+pymdown-extensions==10.4
+apispec==6.6.1
+apispec[validation]
+apispec-webframeworks
+apispec[yaml]
diff --git a/docs/src/apps/example.ipynb b/docs/src/apps/example.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Developing Apps\n",
+    "# Example API Usage\n",
     "\n",
     "The Nesis' API gives you the ability to develop apps (new apps or extend existing apps) that interact with your private document and data repositories. Using Nesis' security model, you are able to apply role based access control to your data such that users are only able to seamlessly access data tied to their security profile.\n",
     "\n",
@@ -104,8 +104,14 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "admin_api_headers = {'Content-Type': 'application/json', 'Authorization': f'Bearer {admin_api_key}'}\n",
-    "prediction_api_header = {'Content-Type': 'application/json', 'Authorization': f'Bearer {predictions_api_key}'}"
+    "admin_api_headers = {\n",
+    "    \"Content-Type\": \"application/json\",\n",
+    "    \"Authorization\": f\"Bearer {admin_api_key}\",\n",
+    "}\n",
+    "prediction_api_header = {\n",
+    "    \"Content-Type\": \"application/json\",\n",
+    "    \"Authorization\": f\"Bearer {predictions_api_key}\",\n",
+    "}"
    ]
   },
   {
@@ -114,7 +120,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "datasource = {\"type\": \"minio\", \"name\": \"documents\", \"connection\": {\"user\": \"your_username\",\"password\":\"your_password\",\"endpoint\": \"http://minio:port\",\"dataobjects\": \"bucket-name\"}}"
+    "datasource = {\n",
+    "    \"type\": \"minio\",\n",
+    "    \"name\": \"documents\",\n",
+    "    \"connection\": {\n",
+    "        \"user\": \"your_username\",\n",
+    "        \"password\": \"your_password\",\n",
+    "        \"endpoint\": \"http://minio:port\",\n",
+    "        \"dataobjects\": \"bucket-name\",\n",
+    "    },\n",
+    "}"
    ]
   },
   {
@@ -123,7 +138,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "datasource_response = requests.post(f'{nesis_api_endpoint}/datasources', headers=admin_api_headers, json=datasource)"
+    "datasource_response = requests.post(\n",
+    "    f\"{nesis_api_endpoint}/datasources\", headers=admin_api_headers, json=datasource\n",
+    ")"
    ]
   },
   {
@@ -151,18 +168,12 @@
     "role = {\n",
     "    \"name\": \"data-reader\",\n",
     "    \"policy\": {\n",
-    "      \"items\": [\n",
-    "        {\n",
-    "          \"action\": \"create\",\n",
-    "          \"resource\": \"predictions/*\"\n",
-    "        },\n",
-    "        {\n",
-    "          \"action\": \"read\",\n",
-    "          \"resource\": \"datasources/*\"\n",
-    "        }\n",
-    "      ]\n",
-    "    }\n",
-    "}\n"
+    "        \"items\": [\n",
+    "            {\"action\": \"create\", \"resource\": \"predictions/*\"},\n",
+    "            {\"action\": \"read\", \"resource\": \"datasources/*\"},\n",
+    "        ]\n",
+    "    },\n",
+    "}"
    ]
   },
   {
@@ -171,7 +182,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "role_response = requests.post(f'{nesis_api_endpoint}/roles', headers=admin_api_headers, json=role)"
+    "role_response = requests.post(\n",
+    "    f\"{nesis_api_endpoint}/roles\", headers=admin_api_headers, json=role\n",
+    ")"
    ]
   },
   {
@@ -214,7 +227,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "user_response = requests.post(f'{nesis_api_endpoint}/users', headers=admin_api_headers, json={'email': 'test.email@domain.com', 'name': 'Da Zone', 'password': 'P@ssword', 'roles': [role['id']]})"
+    "user_response = requests.post(\n",
+    "    f\"{nesis_api_endpoint}/users\",\n",
+    "    headers=admin_api_headers,\n",
+    "    json={\n",
+    "        \"email\": \"test.email@domain.com\",\n",
+    "        \"name\": \"Da Zone\",\n",
+    "        \"password\": \"P@ssword\",\n",
+    "        \"roles\": [role[\"id\"]],\n",
+    "    },\n",
+    ")"
    ]
   },
   {
@@ -259,7 +281,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "prediction_response = requests.post(f'{nesis_api_endpoint}/modules/qanda/predictions', headers=prediction_api_header, json={'query': 'summarize the only office agreement'})"
+    "prediction_response = requests.post(\n",
+    "    f\"{nesis_api_endpoint}/modules/qanda/predictions\",\n",
+    "    headers=prediction_api_header,\n",
+    "    json={\"query\": \"summarize the only office agreement\"},\n",
+    ")"
    ]
   },
   {
@@ -293,7 +319,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "prediction_response = requests.post(f'{nesis_api_endpoint}/modules/qanda/predictions', headers={**prediction_api_header, 'X-Nesis-Request-UserKey': user['id']}, json={'query': 'summarize the only office agreement'})"
+    "prediction_response = requests.post(\n",
+    "    f\"{nesis_api_endpoint}/modules/qanda/predictions\",\n",
+    "    headers={**prediction_api_header, \"X-Nesis-Request-UserKey\": user[\"id\"]},\n",
+    "    json={\"query\": \"summarize the only office agreement\"},\n",
+    ")"
    ]
   },
   {

diff --git a/docs/src/apps/swagger.md b/docs/src/apps/swagger.md
@@ -0,0 +1 @@
+[OAD(./src/apps/swagger.yaml)]