On-demand report generation docs (#56)

Spikatrix · web-flow · commit 225801ce2a29 · 2024-07-09T18:02:59.000+05:30
* Ondemand report input schema format

* On-demand reporting docs

* CodeRabbit suggestions

* Typo
diff --git a/docs/guides/images/api_keys.png b/docs/guides/images/api_keys.png
diff --git a/docs/guides/ondemand-reports.md b/docs/guides/ondemand-reports.md
@@ -0,0 +1,70 @@
+---
+title: On-demand Reports
+sidebar_label: On-demand Reports (Beta)
+description:
+  CodeRabbit offers a way to generate on-demand reports using a simple API request
+sidebar_position: 5
+---
+
+```mdx-code-block
+import ReportSchema from "@site/src/components/ReportSchema";
+```
+
+:::info
+
+This feature is in beta
+
+:::
+
+CodeRabbit offers a way to generate on-demand reports using the [CodeRabbit API](https://api.coderabbit.ai/api/swagger/).  
+You will need an API Key to access the CodeRabbit API and generate an on-demand report.
+
+## Create an API key
+
+Sign in to your CodeRabbit account and navigate to the [**API Keys**](https://app.coderabbit.ai/settings/api-keys) page under 'Organization Settings' in the left sidebar.  
+Click on the **Create API Key** button and enter a name for the API Key.  
+Copy the API key, and keep it safe as it won't be visible again.
+
+![API Keys](./images/api_keys.png)
+
+## Generate an On-demand report
+
+Once you have the API key, pass it in the `x-coderabbitai-api-key` header when calling the API:
+
+```sh
+curl -X 'POST' \
+  'https://api.coderabbit.ai/api/v1/report.generate' \
+  -H 'accept: application/json' \
+  -H 'x-coderabbitai-api-key: cr-xxxxxxxxxxxxx' \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "from": "2024-05-01",
+    "to": "2024-05-15"
+  }'
+```
+
+Sample output:
+
+```sh
+[
+  {
+    "group": "Developer Activity",
+    "report": "*Developer Activity*:\n\n 🟢 **Update README.md** [#10](https://gitlab.com/master-group123/sub-group/project1/-/merge_requests/10)\n• Summary: The change updates the project description and modifies a section header for clearer instructions.\n• Last activity: 1 day ago, mergeable\n• Insights:\n - :magnifying_glass: @user2 Suggested updating the wording to make it clearer"
+  }
+]
+```
+
+
+:::info
+
+If you get a 401 UNAUTHORIZED error, check if you're passing the right API key in the `x-coderabbitai-api-key` header
+
+:::
+
+The on-demand report generation endpoints take in inputs as per the schema shown below:
+
+```mdx-code-block
+<ReportSchema />
+```
+
+[API Reference](https://api.coderabbit.ai/api/swagger/)
diff --git a/src/components/ReportSchema.tsx b/src/components/ReportSchema.tsx
@@ -0,0 +1,6 @@
+import Schema from "@site/static/schema/reporting.json";
+import JSONSchemaViewer from "@theme/JSONSchemaViewer";
+
+export default function Viewer(): JSX.Element {
+  return <JSONSchemaViewer schema={Schema} />;
+}
diff --git a/static/schema/reporting.json b/static/schema/reporting.json
@@ -0,0 +1,93 @@
+{
+	"type": "object",
+	"properties": {
+		"scheduleRange": {
+			"type": "string",
+			"enum": [
+				"Dates"
+			]
+		},
+		"from": {
+			"type": "string",
+			"format": "date"
+		},
+		"to": {
+			"type": "string",
+			"format": "date"
+		},
+		"prompt": {
+			"type": "string"
+		},
+		"promptTemplate": {
+			"type": "string",
+			"enum": [
+				"Daily Standup Report",
+				"Sprint Report",
+				"Release Notes",
+				"Custom"
+			]
+		},
+		"parameters": {
+			"type": "array",
+			"items": {
+				"type": "object",
+				"properties": {
+					"parameter": {
+						"type": "string",
+						"enum": [
+							"REPOSITORY",
+							"LABEL",
+							"TEAM",
+							"USER"
+						]
+					},
+					"operator": {
+						"type": "string",
+						"enum": [
+							"IN",
+							"ALL"
+						]
+					},
+					"values": {
+						"type": "array",
+						"items": {
+							"type": "string"
+						}
+					}
+				},
+				"required": [
+					"parameter",
+					"operator",
+					"values"
+				],
+				"additionalProperties": false
+			}
+		},
+		"groupBy": {
+			"type": "string",
+			"enum": [
+				"NONE",
+				"REPOSITORY",
+				"LABEL",
+				"TEAM",
+				"USER"
+			]
+		},
+		"subgroupBy": {
+			"type": "string",
+			"enum": [
+				"NONE",
+				"REPOSITORY",
+				"LABEL",
+				"TEAM",
+				"USER"
+			]
+		}
+	},
+	"required": [
+		"from",
+		"to"
+	],
+	"additionalProperties": false,
+	"$schema": "http://json-schema.org/draft-07/schema#"
+}
