API Docs: implement custom OpenAPI component

docs/api/cody.mdx

@@ -0,0 +1,13 @@
+# Sourcegraph Cody API
+
+## `POST /.api/cody/context`
+<ApiOperation operation="POST /.api/cody/context" />
+
+## `POST /.api/llm/chat/completions`
+<ApiOperation operation="POST /.api/llm/chat/completions" />
+
+## `GET /.api/llm/models`
+<ApiOperation operation="GET /.api/llm/models" />
+
+## `GET /.api/llm/models/{modelId}`
+<ApiOperation operation="GET /.api/llm/models/{modelId}" />

docs/api/index.mdx

@@ -3,4 +3,5 @@
 Sourcegraph exposes the following APIs:
 
 - [Sourcegraph GraphQL API](/api/graphql/), for accessing data stored or computed by Sourcegraph
+- [Sourcegraph Cody API](/api/cody/), for interacting with Cody.
 - [Sourcegraph Stream API](/api/stream_api/), for consuming search results as a stream of events

package.json

@@ -6,7 +6,8 @@
 		"dev": "next dev",
 		"build": "next build",
 		"start": "next start",
-		"lint": "next lint"
+		"lint": "next lint",
+		"openapi:watch": "./scripts/openapi-watch.sh"
 	},
 	"browserslist": "defaults, not ie <= 11",
 	"dependencies": {
@@ -46,6 +47,7 @@
 		"react": "18.3.1",
 		"react-dom": "18.3.1",
 		"react-highlight-words": "^0.20.0",
+		"react-markdown": "^9.0.1",
 		"react-syntax-highlighter": "^15.5.0",
 		"rehype-autolink-headings": "^7.1.0",
 		"rehype-pretty-code": "^0.10.2",

scripts/openapi-compile.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+set -eux
+
+# Check if yq is installed, if not, install it using Homebrew
+if ! command -v yq &> /dev/null
+then
+    echo "yq could not be found, installing via Homebrew..."
+    if ! command -v brew &> /dev/null
+    then
+        echo "Homebrew is not installed. Please install Homebrew first."
+        exit 1
+    fi
+    brew install yq
+fi
+
+
+SOURCEGRAPH_DIR=$1
+DOCS_DIR=$2
+cd "$SOURCEGRAPH_DIR"
+pnpm -C internal/openapi compile
+yq eval -o=json internal/openapi/tsp-output/@typespec/openapi3/openapi.Sourcegraph.Latest.yaml > "$DOCS_DIR"/src/components/openapi/openapi.Sourcegraph.Latest.json

scripts/openapi-watch.sh

@@ -0,0 +1,16 @@
+#!/bin/bash
+set -eux
+
+
+# Check if entr is installed
+if ! command -v entr &> /dev/null
+then
+    echo "entr could not be found, installing with Homebrew..."
+    brew install entr
+fi
+
+COMPILE_SCRIPT=$(dirname "${BASH_SOURCE[0]}")/openapi-compile.sh
+DOCS_DIR=$(realpath $(dirname "${BASH_SOURCE[0]}")/../)
+SOURCEGRAPH_DIR=${SOURCEGRAPH_DIR:-$(dirname "${BASH_SOURCE[0]}")/../../sourcegraph}
+SOURCEGRAPH_DIR=$(realpath $SOURCEGRAPH_DIR)
+echo $SOURCEGRAPH_DIR/internal/openapi/public.tsp | entr $COMPILE_SCRIPT $SOURCEGRAPH_DIR $DOCS_DIR

src/components/MdxComponents.tsx

@@ -1,6 +1,7 @@
 import AWSOneClickLaunchForm from './AWSOneClickLaunchForm';
 import { ContentTab, ContentTabs } from './ContentTabs';
 import FeatureParity from './FeatureParity';
+import { PreCode, PreCodeBlock } from './PreCodeBlock';
 import Accordion from './mdx/Accordion';
 import { Callout } from './mdx/Callout';
 import { CustomLink } from './mdx/CustomLink';
@@ -9,12 +10,13 @@ import { LinkCard, LinkCards } from './mdx/LinkCards';
 import { ProductCard, ProductCards } from './mdx/ProductCards';
 import { QuickLink, QuickLinks } from './mdx/QuickLinks';
 import { Tab, Tabs } from './mdx/Tabs';
-import { PreCodeBlock, PreCode } from './PreCodeBlock';
+import { ApiOperation } from './openapi/ApiOperation';
 import ResourceEstimator from './resource-estimator/ResourceEstimator';
 import { Badge } from './ui/badge';
 
 const MdxComponents = (version?: string) => {
   return {
+    ApiOperation,
     FeatureParity,
     ResourceEstimator,
     AWSOneClickLaunchForm,

src/components/mdx/Tabs.tsx

@@ -68,6 +68,7 @@ export function Tabs({children}: TabsProps) {
 }
 
 interface TabProps {
+	title?: string;
 	children: ReactNode;
 }