(do not merge): feat(cli): specify openrpc in docs.yml

fern/apis/docs-yml/definition/docs.yml

@@ -567,6 +567,9 @@ types:
       "api-name":
         type: optional<string>
         docs: Name of API that we are referencing
+      openrpc: 
+        type: optional<string>
+        docs: Path to an openrpc spec. This is experimental. 
       audiences: optional<list<AudienceId>>
       display-errors:
         type: optional<boolean>

packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts

@@ -649,6 +649,7 @@ async function convertNavigationItem({
     if (isRawApiSectionConfig(rawConfig)) {
         return {
             type: "apiSection",
+            openrpc: rawConfig.openrpc ?? undefined,
             title: rawConfig.api,
             icon: rawConfig.icon,
             apiName: rawConfig.apiName ?? undefined,

packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts

@@ -220,6 +220,7 @@ export declare namespace DocsNavigationItem {
         title: string;
         icon: string | undefined;
         apiName: string | undefined;
+        openrpc: string | undefined;
         audiences: Audiences;
         showErrors: boolean;
         snippetsConfiguration: SnippetsConfiguration | undefined;

packages/cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/ApiReferenceConfiguration.ts

@@ -8,6 +8,8 @@ export interface ApiReferenceConfiguration extends FernDocsConfig.WithPermission
     api: string;
     /** Name of API that we are referencing */
     apiName?: string;
+    /** Path to an openrpc spec. This is experimental. */
+    openrpc?: string;
     audiences?: FernDocsConfig.AudienceId[];
     /** Defaults to false */
     displayErrors?: boolean;

packages/cli/configuration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/ApiReferenceConfiguration.ts

@@ -17,6 +17,7 @@ export const ApiReferenceConfiguration: core.serialization.ObjectSchema<
     .object({
         api: core.serialization.string(),
         apiName: core.serialization.property("api-name", core.serialization.string().optional()),
+        openrpc: core.serialization.string().optional(),
         audiences: core.serialization.list(AudienceId).optional(),
         displayErrors: core.serialization.property("display-errors", core.serialization.boolean().optional()),
         snippets: SnippetsConfiguration.optional(),
@@ -37,6 +38,7 @@ export declare namespace ApiReferenceConfiguration {
     export interface Raw extends WithPermissions.Raw {
         api: string;
         "api-name"?: string | null;
+        openrpc?: string | null;
         audiences?: AudienceId.Raw[] | null;
         "display-errors"?: boolean | null;
         snippets?: SnippetsConfiguration.Raw | null;

packages/cli/docs-resolver/package.json

@@ -31,7 +31,7 @@
     "@fern-api/configuration-loader": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-markdown-utils": "workspace:*",
-    "@fern-api/docs-parsers": "^0.0.26",
+    "@fern-api/docs-parsers": "0.0.37",
     "@fern-api/fdr-sdk": "0.127.5-c465d2cf0",
     "@fern-api/lazy-fern-workspace": "workspace:*",
     "@fern-api/ui-core-utils": "0.127.5-c465d2cf0",
@@ -45,7 +45,8 @@
     "gray-matter": "^4.0.3",
     "lodash-es": "^4.17.21",
     "url-join": "^5.0.0",
-    "openapi-types": "^12.1.3"
+    "openapi-types": "^12.1.3",
+    "@open-rpc/meta-schema": "^1.14.9"
   },
   "devDependencies": {
     "@fern-api/configs": "workspace:*",

packages/cli/docs-resolver/src/ApiReferenceNodeConverterLatest.ts

@@ -58,7 +58,7 @@ export class ApiReferenceNodeConverterLatest {
         private apiSection: docsYml.DocsNavigationItem.ApiSection,
         api: FdrAPI.api.latest.ApiDefinition,
         parentSlug: FernNavigation.V1.SlugGenerator,
-        private workspace: OSSWorkspace,
+        private workspace: OSSWorkspace | undefined,
         private docsWorkspace: DocsWorkspace,
         private taskContext: TaskContext,
         private markdownFilesToFullSlugs: Map<AbsoluteFilePath, string>,
@@ -104,7 +104,7 @@ export class ApiReferenceNodeConverterLatest {
         const pointsTo = FernNavigation.V1.followRedirects(this.#children);
         const changelogNodeConverter = new ChangelogNodeConverter(
             this.markdownFilesToFullSlugs,
-            this.workspace.changelog?.files.map((file) => file.absoluteFilepath),
+            this.workspace?.changelog?.files.map((file) => file.absoluteFilepath),
             this.docsWorkspace,
             this.#idgen
         ).orUndefined();

packages/cli/docs-resolver/src/DocsDefinitionResolver.ts

@@ -14,13 +14,13 @@ import {
     replaceReferencedCode,
     replaceReferencedMarkdown
 } from "@fern-api/docs-markdown-utils";
-import { APIV1Read, APIV1Write, DocsV1Write, FdrAPI, FernNavigation } from "@fern-api/fdr-sdk";
-import { AbsoluteFilePath, RelativeFilePath, listFiles, relative, resolve } from "@fern-api/fs-utils";
+import { APIV1Write, DocsV1Write, FdrAPI, FernNavigation } from "@fern-api/fdr-sdk";
+import { AbsoluteFilePath, RelativeFilePath, doesPathExist, listFiles, relative, resolve } from "@fern-api/fs-utils";
 import { generateIntermediateRepresentation } from "@fern-api/ir-generator";
 import { IntermediateRepresentation } from "@fern-api/ir-sdk";
 import { OSSWorkspace } from "@fern-api/lazy-fern-workspace";
 import { TaskContext } from "@fern-api/task-context";
-import { AbstractAPIWorkspace, DocsWorkspace, FernWorkspace } from "@fern-api/workspace-loader";
+import { DocsWorkspace, FernWorkspace } from "@fern-api/workspace-loader";
 
 import { ApiReferenceNodeConverter } from "./ApiReferenceNodeConverter";
 import { ApiReferenceNodeConverterLatest } from "./ApiReferenceNodeConverterLatest";
@@ -29,6 +29,7 @@ import { NodeIdGenerator } from "./NodeIdGenerator";
 import { convertDocsSnippetsConfigToFdr } from "./utils/convertDocsSnippetsConfigToFdr";
 import { convertIrToApiDefinition } from "./utils/convertIrToApiDefinition";
 import { generateFdrFromOpenApiWorkspace } from "./utils/generateFdrFromOpenApiWorkspace";
+import { generateFdrFromOpenrpc } from "./utils/generateFdrFromOpenrpc";
 import { collectFilesFromDocsConfig } from "./utils/getImageFilepathsToUpload";
 import { visitNavigationAst } from "./visitNavigationAst";
 import { wrapWithHttps } from "./wrapWithHttps";
@@ -593,6 +594,35 @@ export class DocsDefinitionResolver {
         item: docsYml.DocsNavigationItem.ApiSection,
         parentSlug: FernNavigation.V1.SlugGenerator
     ): Promise<FernNavigation.V1.ApiReferenceNode> {
+        if (item.openrpc != null) {
+            const absoluteFilepathToOpenrpc = resolve(
+                this.docsWorkspace.absoluteFilePath,
+                RelativeFilePath.of(item.openrpc)
+            );
+            if (!(await doesPathExist(absoluteFilepathToOpenrpc))) {
+                throw new Error(`OpenRPC file does not exist at path: ${absoluteFilepathToOpenrpc}`);
+            }
+            const api = await generateFdrFromOpenrpc(absoluteFilepathToOpenrpc, this.taskContext);
+            if (api == null) {
+                throw new Error("Failed to generate API Definition from OpenRPC document");
+            }
+            await this.registerApiV2({
+                api,
+                apiName: item.apiName
+            });
+            const node = new ApiReferenceNodeConverterLatest(
+                item,
+                api,
+                parentSlug,
+                undefined,
+                this.docsWorkspace,
+                this.taskContext,
+                this.markdownFilesToFullSlugs,
+                this.#idgen
+            );
+            return node.get();
+        }
+
         if (this.parsedDocsConfig.experimental?.openapiParserV2) {
             const workspace = this.getOpenApiWorkspaceForApiSection(item);
             const api = await generateFdrFromOpenApiWorkspace(workspace, this.taskContext);

packages/cli/docs-resolver/src/utils/generateFdrFromOpenrpc.ts

@@ -0,0 +1,29 @@
+import { OpenrpcDocument } from "@open-rpc/meta-schema";
+import { readFile } from "fs/promises";
+
+import { OpenrpcContext, OpenrpcDocumentConverterNode } from "@fern-api/docs-parsers";
+import { AbsoluteFilePath } from "@fern-api/fs-utils";
+import { TaskContext } from "@fern-api/task-context";
+
+export async function generateFdrFromOpenrpc(
+    openrpcPath: AbsoluteFilePath,
+    context: TaskContext
+): Promise<ReturnType<OpenrpcDocumentConverterNode["convert"]>> {
+    // Read and parse the OpenRPC document
+    const openrpcContent = await readFile(openrpcPath, "utf-8");
+    const openrpcDocument = JSON.parse(openrpcContent) as OpenrpcDocument;
+
+    const openrpcContext = new OpenrpcContext({
+        openrpc: openrpcDocument,
+        logger: context.logger
+    });
+
+    const openrpcFdrJson = new OpenrpcDocumentConverterNode({
+        input: openrpcDocument,
+        context: openrpcContext,
+        accessPath: [],
+        pathId: "openrpc"
+    });
+
+    return openrpcFdrJson.convert();
+}