feat: Adds script to render API docs

HHS · Jan 14, 2025 · 553c52f · 553c52f
1 parent e5e8f07
commit 553c52f
Show file tree

Hide file tree

Showing 4 changed files with 20 additions and 6 deletions.
diff --git a/examples/custom-api/package-lock.json b/examples/custom-api/package-lock.json
diff --git a/examples/custom-api/package.json b/examples/custom-api/package.json
@@ -8,7 +8,10 @@
     "lint": "eslint . --fix",
     "format": "prettier --write . && tsp format lib",
     "check:lint": "eslint",
-    "check:format": "prettier --check . && tsp format lib --check"
+    "check:format": "prettier --check . && tsp format lib --check",
+    "docs:build": "npx @redocly/cli build-docs tsp-output/@typespec/openapi3/openapi.yaml --output ./dist/redocly.html",
+    "docs:preview": "open ./dist/redocly.html",
+    "docs": "npm run typespec && npm run docs:build && npm run docs:preview"
   },
   "peerDependencies": {
     "@opportunity-stream/core": "file:../../specs/opportunity-stream-core-0.1.0-alpha.1.tgz",

diff --git a/examples/custom-api/src/routes.tsp b/examples/custom-api/src/routes.tsp
@@ -13,11 +13,16 @@ namespace CustomAPI.CustomRoutes;
 // Reuse the existing routes, extending functionality
 interface CustomOpportunities extends Routes.Opportunities {
     // Override the existing @read() route with the custom model
-    @get read(@path id: string): CustomModels.CustomOpportunity;
+    @summary("View opportunity")
+    @doc("View the details for a given opportunity")
+    @get
+    read(@path id: string): CustomModels.CustomOpportunity;
 
     // Add a new route with the custom model
+    @summary("Update opportunity")
+    @doc("Update a given opportunity's details")
     @put
-    updatePet(@path id: string, @body data: CustomModels.CustomOpportunity): {
+    update(@path id: string, @body data: CustomModels.CustomOpportunity): {
         @statusCode statusCode: 200;
         @body result: CustomModels.CustomOpportunity;
     };

diff --git a/specs/lib/routes/opportunities.tsp b/specs/lib/routes/opportunities.tsp
@@ -11,7 +11,13 @@ using TypeSpec.Rest;
 // Define the `/opportunities` router
 @route("/opportunities")
 interface Opportunities {
-  @get list(): Models.Opportunity[];
+  @summary("List opportunities")
+  @doc("Get a list of opportunities")
+  @get
+  list(): Models.Opportunity[];
 
-  @get read(@path title: string): Models.Opportunity;
+  @summary("View opportunity")
+  @doc("View additional details about an opportunity")
+  @get
+  read(@path title: string): Models.Opportunity;
 }