feat: generate docs from openapi with a script (#1235)

Co-authored-by: Shahar Glazner <[email protected]>

docs/api-ref/alerts/assign-alert.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /alerts/{fingerprint}/assign/{last_received}
+---

docs/api-ref/alerts/delete-alert.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /alerts
+---

docs/api-ref/alerts/enrich-alert.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /alerts/enrich
+---

docs/api-ref/alerts/get-alert-history.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /alerts/{fingerprint}/history
+---

docs/api-ref/alerts/get-alert.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /alerts/{fingerprint}
+---

docs/api-ref/alerts/get-all-alerts.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /alerts
+---

docs/api-ref/alerts/receive-generic-event.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /alerts/event
+---

docs/api-ref/alerts/search-alerts.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /alerts/search
+---

docs/api-ref/enrichment/create-extraction-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /extraction
+---

docs/api-ref/enrichment/create-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /mapping
+---

docs/api-ref/enrichment/delete-extraction-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /extraction/{rule_id}
+---

docs/api-ref/enrichment/delete-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /mapping/{rule_id}
+---

docs/api-ref/enrichment/get-extraction-rules.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /extraction
+---

docs/api-ref/enrichment/get-rules.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /mapping
+---

docs/api-ref/enrichment/update-extraction-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /extraction/{rule_id}
+---

docs/api-ref/enrichment/update-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /mapping
+---

docs/api-ref/groups/get-groups.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /groups/
+---

docs/api-ref/preset/create-preset.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /preset
+---

docs/api-ref/preset/delete-preset.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /preset/{uuid}
+---

docs/api-ref/preset/get-presets.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /preset
+---

docs/api-ref/preset/update-preset.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /preset/{uuid}
+---

docs/api-ref/providers/get-installed-providers.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /providers/export
+---

docs/api-ref/providers/install-provider-oauth2.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /providers/install/oauth2/{provider_type}
+---

docs/api-ref/providers/invoke-provider-method.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /providers/{provider_id}/invoke/{method}
+---

docs/api-ref/providers/update-provider.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /providers/{provider_id}
+---

docs/api-ref/providers/validate-provider-scopes.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /providers/{provider_id}/scopes
+---

docs/api-ref/pusher/pusher-authentication.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /pusher/auth
+---

docs/api-ref/rules/create-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /rules
+---

docs/api-ref/rules/delete-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /rules/{rule_id}
+---

docs/api-ref/rules/get-rules.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /rules
+---

docs/api-ref/rules/update-rule.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /rules/{rule_id}
+---

docs/api-ref/settings/create-key.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /settings/apikey
+---

docs/api-ref/settings/create-user.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /settings/users
+---

docs/api-ref/settings/delete-api-key.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /settings/apikey/{keyId}
+---

docs/api-ref/settings/delete-smtp-settings.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /settings/smtp
+---

docs/api-ref/settings/delete-user.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /settings/users/{user_email}
+---

docs/api-ref/settings/get-keys.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /settings/apikeys
+---

docs/api-ref/settings/get-smtp-settings.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /settings/smtp
+---

docs/api-ref/settings/get-users.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /settings/users
+---

docs/api-ref/settings/test-smtp-settings.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /settings/smtp/test
+---

docs/api-ref/settings/update-api-key.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /settings/apikey
+---

docs/api-ref/settings/update-smtp-settings.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /settings/smtp
+---

docs/api-ref/status/status.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /status
+---

docs/api-ref/users/delete-user.mdx

@@ -0,0 +1,3 @@
+---
+openapi: delete /users/{user_email}
+---

docs/api-ref/whoami/get-tenant-id.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /whoami
+---

docs/api-ref/workflows/get-raw-workflow-by-id.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /workflows/{workflow_id}/raw
+---

docs/api-ref/workflows/get-workflow-executions-by-alert-fingerprint.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /workflows/executions
+---

docs/api-ref/workflows/get-workflow-executions.mdx

@@ -0,0 +1,3 @@
+---
+openapi: get /workflows/executions/list
+---

docs/api-ref/workflows/run-workflow-from-definition.mdx

@@ -0,0 +1,3 @@
+---
+openapi: post /workflows/test
+---

docs/api-ref/workflows/update-workflow-by-id.mdx

@@ -0,0 +1,3 @@
+---
+openapi: put /workflows/{workflow_id}
+---

docs/generate_readme_from_openapijson.sh

@@ -0,0 +1,8 @@
+
+#!/bin/bash
+
+# Before running this script, make sure you have update the openapi.json from the backend, (/docs route)
+
+python3 openapi_converter.py --source ./openapi.json --dest ./openapi_converted.json
+npx @mintlify/scraping@latest openapi-file ./openapi_converted.json -o ./api-ref
+rm ./openapi_converted.json

docs/openapi_converter.py

@@ -0,0 +1,63 @@
+from argparse import ArgumentParser
+import typing as t
+import json
+Json = dict[str | t.Literal["anyOf", "type"], "Json"] | list["Json"] | str | bool
+
+
+## Reference: https://github.com/tiangolo/fastapi/discussions/9789
+def convert_3_dot_1_to_3_dot_0(json: dict[str, Json]):
+    """Will attempt to convert version 3.1.0 of some openAPI json into 3.0.2
+
+    Usage:
+
+        >>> from pprint import pprint
+        >>> json = {
+        ...     "some_irrelevant_keys": {...},
+        ...     "nested_dict": {"nested_key": {"anyOf": [{"type": "string"}, {"type": "null"}]}},
+        ...     "examples": [{...}, {...}]
+        ... }
+        >>> convert_3_dot_1_to_3_dot_0(json)
+        >>> pprint(json)
+        {'example': {Ellipsis},
+         'nested_dict': {'nested_key': {'anyOf': [{'type': 'string'}],
+                                        'nullable': True}},
+         'openapi': '3.0.2',
+         'some_irrelevant_keys': {Ellipsis}}
+    """
+    json["openapi"] = "3.0.2"
+
+    def inner(yaml_dict: Json):
+        if isinstance(yaml_dict, dict):
+            if "anyOf" in yaml_dict and isinstance((anyOf := yaml_dict["anyOf"]), list):
+                for i, item in enumerate(anyOf):
+                    if isinstance(item, dict) and item.get("type") == "null":
+                        anyOf.pop(i)
+                        yaml_dict["nullable"] = True
+            if "examples" in yaml_dict:
+                examples = yaml_dict["examples"]
+                del yaml_dict["examples"]
+                if isinstance(examples, list) and len(examples):
+                    yaml_dict["example"] = examples[0]
+            for value in yaml_dict.values():
+                inner(value)
+        elif isinstance(yaml_dict, list):
+            for item in yaml_dict:
+                inner(item)
+
+    inner(json)
+    return json
+
+if __name__ == "__main__":
+
+    parser = ArgumentParser(description="Script for converting openapi version 3.1.0 to 3.0.2")
+    parser.add_argument("-s", "--source", help="The path to openapi.json")
+    parser.add_argument("-d", "--dest", help="The path to output")
+
+    args = parser.parse_args()
+
+    with open(args.source, "r") as fd:
+        content = json.load(fd)
+
+    output = json.dumps(convert_3_dot_1_to_3_dot_0(content))
+    with open(args.dest, "wt") as wt:
+        wt.write(output)