feat: auto OpenAPI spec JSON, generate MDX files and update mint.json (…

…#231)

* Generate OpenAPI spec JSON at build time

* Auto generate spec JSON at build time

* Edit - project.json

* Some minor refactor

* Remove the openapi.json file - we can generate at build time

* Autogenerate OpenAPI JSON, scrape the JSON, generate MDX files and update mint.json

* Added @mintlify/scraping version to ensure that the scraped output is consistent

apps/server/project.json

@@ -87,6 +87,9 @@
       "command": "GITHUB_ACTIONS=true npx ts-node -P apps/server/tsconfig.app.json -r tsconfig-paths/register apps/server/scripts/generate-graphql-schema.ts",
       "outputs": ["{projectRoot}/schema.graphql"]
     },
+    "generate-open-api-spec": {
+      "command": "npx ts-node -P apps/server/tsconfig.app.json -r tsconfig-paths/register apps/server/scripts/generate-openapi-spec-json.ts"
+    },
     "graphql:codegen": {
       "dependsOn": ["graphql:schema-generate"],
       "command": "OFFLINE=true npx graphql-codegen"

apps/server/scripts/generate-openapi-spec-json.ts

@@ -0,0 +1,65 @@
+import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
+import { AppModule } from "../src/app/app.module";
+import { NestFactory } from "@nestjs/core";
+import path from "path";
+import fs from "fs";
+import { execSync } from "child_process";
+import { stderr } from "process";
+
+export default async function generateOpenAPISpecJSON() {
+  const app = await NestFactory.create(AppModule);
+
+  // Swagger setup
+  const config = new DocumentBuilder()
+    .setTitle("Pezzo API")
+    .setDescription(
+      "Specification of the Pezzo REST API, used by various clients."
+    )
+    .setVersion("1.0")
+    .build();
+  const document = SwaggerModule.createDocument(app, config);
+  const docsPath = path.join(__dirname, "../../../docs/");
+  const outputFilePath = path.join(docsPath, "openapi.json");
+  fs.writeFileSync(outputFilePath, JSON.stringify(document));
+  console.log("Generated OpenAPI spec");
+
+  let scrapedOutput = "";
+
+  console.log("Scraping the generated OpenAPI JSON");
+
+  scrapedOutput = execSync(
+    `cd ${docsPath} && npx --yes @mintlify/[email protected] openapi-file openapi.json -o api-reference`,
+    { encoding: "utf-8" }
+  );
+
+  console.log(
+    "Scraped the OpenAPI JSON file and generated the MDX files for it"
+  );
+
+  const mintJSON = fs.readFileSync(path.join(docsPath, "mint.json"), {
+    encoding: "utf-8",
+  });
+
+  const mint = JSON.parse(mintJSON);
+
+  mint.navigation = mint.navigation.filter((navigationItem) => {
+    const pages: string[] = navigationItem.pages;
+    if (pages.length < 1) return true;
+    for (let i = 0; i < pages.length; i++) {
+      const path = pages[i];
+      if (path.startsWith("api-reference/")) return false;
+    }
+    return true;
+  });
+
+  scrapedOutput = scrapedOutput.slice(scrapedOutput.indexOf("["));
+  mint.navigation.push(...JSON.parse(scrapedOutput));
+  fs.writeFileSync(
+    path.join(docsPath, "mint.json"),
+    JSON.stringify(mint, null, 2)
+  );
+  console.log("Updated mint.json file");
+  process.exit(0);
+}
+
+generateOpenAPISpecJSON();

docs/api-reference/cache/retrieve-cached-request.mdx

@@ -1,3 +1,3 @@
 ---
-openapi: post /api/cache/v1/request/retrieve
+openapi: post /cache/v1/request/retrieve
 ---

docs/api-reference/cache/save-request-to-cache.mdx

@@ -1,3 +1,3 @@
 ---
-openapi: post /api/cache/v1/request/save
+openapi: post /cache/v1/request/save
 ---

docs/api-reference/health/performs-a-health-check.mdx

@@ -1,3 +1,3 @@
 ---
-openapi: get /api/healthz
+openapi: get /healthz
 ---

docs/api-reference/prompts/get-the-deployed-prompt-version-to-a-particular-environment.mdx

@@ -1,3 +1,3 @@
 ---
-openapi: get /api/prompts/v2/deployment
+openapi: get /prompts/v2/deployment
 ---

docs/api-reference/reporting/report-a-request.mdx

@@ -1,3 +1,3 @@
 ---
-openapi: post /api/reporting/v2/request
+openapi: post /reporting/v2/request
 ---

docs/mint.json

@@ -29,7 +29,7 @@
     {
       "name": "API Reference",
       "url": "api-reference"
-  }
+    }
   ],
   "navigation": [
     {
@@ -106,10 +106,10 @@
     }
   },
   "api": {
-    "baseUrl": "https://api.staging.pezzo.ai",
+    "baseUrl": "https://api.staging.pezzo.ai/api",
     "playground": {
       "mode": "hide"
     }
   },
-  "openapi": "https://api.staging.pezzo.ai/api/spec-json"
-}
+  "openapi": "./openapi.json"
+}

docs/openapi.json

@@ -0,0 +1 @@
+{"openapi":"3.0.0","paths":{"/healthz":{"get":{"operationId":"HealthController_healthz","summary":"Performs a health check","parameters":[],"responses":{"200":{"description":"Returns the health status and current version"}},"tags":["Health"]}},"/prompts/v2/deployment":{"get":{"operationId":"PromptsController_getPromptDeployment","summary":"Get the deployed Prompt Version to a particular Environment","parameters":[{"name":"name","required":true,"in":"query","description":"The name of the prompt (case sensitive)","example":"PromptName","schema":{"type":"string"}},{"name":"environmentName","required":true,"in":"query","description":"The name of the environment (case sensitive)","example":"Production","schema":{"type":"string"}}],"responses":{"200":{"description":"Deployed prompt version object"},"404":{"description":"Prompt deployment not found for the specific environment name"},"500":{"description":"Internal server error"}},"tags":["Prompts"]}},"/reporting/v2/request":{"post":{"operationId":"ReportingController_reportRequest","summary":"Report a request","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateReportDto"}}}},"responses":{"200":{"description":"Report has been reported successfully"},"500":{"description":"Internal server error"}},"tags":["Reporting"]}},"/cache/v1/request/retrieve":{"post":{"operationId":"CacheController_retrieveCachedRequest","summary":"Retrieve cached request","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RetrieveCacheRequestDto"}}}},"responses":{"200":{"description":"Returns the cached request data."},"404":{"description":"Cached request not found."}},"tags":["Cache"]}},"/cache/v1/request/save":{"post":{"operationId":"CacheController_saveRequestToCache","summary":"Save request to cache","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CacheRequestDto"}}}},"responses":{"200":{"description":"Returns the cache request result."}},"tags":["Cache"]}}},"info":{"title":"Pezzo API","description":"Specification of the Pezzo REST API, used by various clients.","version":"1.0","contact":{}},"tags":[],"servers":[],"components":{"schemas":{"PromptExecutionMetadataDto":{"type":"object","properties":{"provider":{"type":"string","description":"LLM provider","enum":["OpenAI","Azure","Anthropic"]},"client":{"type":"string","description":"Client name identifier","example":"pezzo-ts"},"clientVersion":{"type":"string","description":"Client version","example":"0.4.11"},"environment":{"type":"string","description":"The name of the Environment (case sensitive)","example":"Production"},"promptId":{"type":"string","description":"The ID of the reported prompt (if managed)","example":"c41jd0s93j000ud7kg7vekhi3"}},"required":["provider","client","clientVersion","environment"]},"ExecutionRequestDto":{"type":"object","properties":{"timestamp":{"format":"date-time","type":"string","description":"Request timestamp","example":"2021-01-01T00:00:00.000Z"},"body":{"type":"object","description":"Raw request body, as sent to the LLM","additionalProperties":true}},"required":["timestamp","body"]},"ExecutionResponseDto":{"type":"object","properties":{"timestamp":{"format":"date-time","type":"string","description":"Response timestamp","example":"2021-01-01T00:00:00.000Z"},"body":{"type":"object","description":"Raw response body, as received from the LLM","additionalProperties":true}},"required":["timestamp","body"]},"CreateReportDto":{"type":"object","properties":{"metadata":{"description":"Metadata","allOf":[{"$ref":"#/components/schemas/PromptExecutionMetadataDto"}]},"properties":{"type":"object","description":"Additional properties to be associated with the report","additionalProperties":true,"example":{"userId":"someUserId","traceId":"traceId"}},"request":{"$ref":"#/components/schemas/ExecutionRequestDto"},"response":{"$ref":"#/components/schemas/ExecutionResponseDto"},"cacheEnabled":{"type":"boolean","description":"Whether caching is enabled for the report","default":false},"cacheHit":{"type":"boolean","description":"Whether the report was generated from a cache hit or not","default":false}},"required":["metadata","request","response"]},"RetrieveCacheRequestDto":{"type":"object","properties":{"request":{"type":"object","description":"The request object to retrieve from cache","additionalProperties":true,"example":{"key1":"value1","key2":"value2"}}},"required":["request"]},"CacheRequestDto":{"type":"object","properties":{"request":{"type":"object","description":"The request object to cache","additionalProperties":true,"example":{"key1":"value1","key2":"value2"}},"response":{"type":"object","description":"The response object to cache","additionalProperties":true,"example":{"key1":"value1","key2":"value2"}}},"required":["request","response"]}}}}