API Docs: implement custom OpenAPI component

Previously, there was no easy way to reference docs for our REST API
endpoints. This PR adds a new `<ApiOperation/>` React component that
we can use in MDX files to embed docs for a single API operation. The
component renders the code examples, request schema, and response schema
using existing components like code blocks and HTML tables avoiding the
need for custom CSS styling.

Author: olafurpg

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",

pnpm-lock.yaml

@@ -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-compile.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

scripts/openapi-watch.sh

@@ -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/MdxComponents.tsx

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