Add support for custom code samples (#2842)

* add types * zod and ir * update ir * build * fix generators * update fdr-sdk * publish code samples * move readme extension to another file * add openapi-ir-to-fern * generate json schema * endpoint factory * fixes * fix * update snap * fix format * update ete snapg
fern-api · Jan 31, 2024 · 6f4146c · 6f4146c
1 parent b3efe9a
commit 6f4146c
Show file tree

Hide file tree

Showing 96 changed files with 19,423 additions and 269 deletions.
diff --git a/.pnp.cjs b/.pnp.cjs
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -9,5 +9,8 @@
   "typescript.enablePromptUseWorkspaceTsdk": true,
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": ["source.fixAll", "source.organizeImports", "source.sortMembers"],
-  "editor.defaultFormatter": null
+  "editor.defaultFormatter": null,
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
 }
diff --git a/...44.0-1-geb2e930-a7c9e098e5-2d0b70a66e.zip → ...6.1-18-g26596cb-d574412640-35ed5308ef.zip b/...44.0-1-geb2e930-a7c9e098e5-2d0b70a66e.zip → ...6.1-18-g26596cb-d574412640-35ed5308ef.zip
diff --git a/.yarn/cache/@fern-fern-ir-sdk-npm-0.0.3294-fcd876af76-f7efe8a483.zip b/.yarn/cache/@fern-fern-ir-sdk-npm-0.0.3294-fcd876af76-f7efe8a483.zip
diff --git a/...del-npm-0.0.152-d90bc1b00f-c969d68d7c.zip → ...del-npm-0.0.163-33d1401a1d-36763c2697.zip b/...del-npm-0.0.152-d90bc1b00f-c969d68d7c.zip → ...del-npm-0.0.163-33d1401a1d-36763c2697.zip
diff --git a/fern.schema.dev.json b/fern.schema.dev.json
@@ -546,6 +546,33 @@
                             }
                           },
                           "additionalProperties": false
+                        },
+                        "code-samples": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "name": {
+                                "$ref": "#/properties/types/additionalProperties/anyOf/1/anyOf/0/properties/examples/items/properties/name"
+                              },
+                              "docs": {
+                                "$ref": "#/properties/types/additionalProperties/anyOf/1/anyOf/0/properties/docs"
+                              },
+                              "language": {
+                                "anyOf": [
+                                  {
+                                    "type": "string",
+                                    "enum": ["curl", "python", "javascript", "js", "node", "typescript", "ts", "go"]
+                                  },
+                                  { "type": "string" }
+                                ]
+                              },
+                              "code": { "type": "string" },
+                              "install": { "type": "string" }
+                            },
+                            "required": ["language", "code"],
+                            "additionalProperties": false
+                          }
                         }
                       },
                       "additionalProperties": false

diff --git a/fern.schema.json b/fern.schema.json
@@ -546,6 +546,33 @@
                             }
                           },
                           "additionalProperties": false
+                        },
+                        "code-samples": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "name": {
+                                "$ref": "#/properties/types/additionalProperties/anyOf/1/anyOf/0/properties/examples/items/properties/name"
+                              },
+                              "docs": {
+                                "$ref": "#/properties/types/additionalProperties/anyOf/1/anyOf/0/properties/docs"
+                              },
+                              "language": {
+                                "anyOf": [
+                                  {
+                                    "type": "string",
+                                    "enum": ["curl", "python", "javascript", "js", "node", "typescript", "ts", "go"]
+                                  },
+                                  { "type": "string" }
+                                ]
+                              },
+                              "code": { "type": "string" },
+                              "install": { "type": "string" }
+                            },
+                            "required": ["language", "code"],
+                            "additionalProperties": false
+                          }
                         }
                       },
                       "additionalProperties": false

diff --git a/fern/apis/ir-types-v32/definition/http.yml b/fern/apis/ir-types-v32/definition/http.yml
@@ -205,6 +205,21 @@ types:
       queryParameters: list<ExampleQueryParameter>
       request: optional<ExampleRequestBody>
       response: ExampleResponse
+      codeSamples:
+        availability: in-development
+        type: optional<list<ExampleCodeSample>>
+        docs: |
+          Hand-written code samples for this endpoint.These code samples should match the 
+          example that it's attached to, so that we can spin up an API Playground with
+          the code sample that's being displayed in the API Reference.
+
+  ExampleCodeSample:
+    extends: commons.WithDocs
+    properties:
+      name: optional<commons.Name>
+      language: string
+      code: string
+      install: optional<string>
 
   ExamplePathParameter:
     properties:

diff --git a/fern/apis/openapi-ir/definition/finalIr.yml b/fern/apis/openapi-ir/definition/finalIr.yml
@@ -91,6 +91,35 @@ types:
       server: list<commons.Server>
       examples: list<EndpointExample>
 
+  CustomCodeSample:
+    availability: in-development
+    extends: commons.WithDescription
+    properties:
+      language: SupportedLanguage
+      code:
+        type: string
+        docs: |
+          The code sample. 
+          This is a string because we want to support code samples that are not valid JSON.
+      name: optional<string>
+      install:
+        type: optional<string>
+        docs: |
+          The command to install the dependencies for the code sample.
+          For example, `npm install` or `pip install -r requirements.txt`.
+
+  SupportedLanguage:
+    docs: Syntax highlighting.
+    enum:
+      - curl
+      - python
+      - javascript
+      - js # alias to javascript
+      - node # alias to javascript
+      - typescript
+      - ts # alias to typescript
+      - go
+
   EndpointExample:
     docs: |
       A complete example associated with the endpoint. All child
@@ -102,6 +131,7 @@ types:
       headers: optional<list<HeaderExample>>
       request: optional<example.FullExample>
       response: optional<example.FullExample>
+      codeSamples: list<CustomCodeSample>
 
   PathParameterExample:
     properties:
@@ -403,4 +433,4 @@ types:
       - commons.WithName
       - commons.WithSdkGroupName
     properties:
-      schemas: list<Schema>
+      schemas: list<Schema>
diff --git a/fern/apis/openapi-ir/definition/parseIr.yml b/fern/apis/openapi-ir/definition/parseIr.yml
@@ -3,8 +3,8 @@ imports:
   finalIr: finalIr.yml
 
 types:
-  NamedFullExample: 
-    properties: 
+  NamedFullExample:
+    properties:
       name: optional<string>
       value: unknown
 
@@ -40,6 +40,11 @@ types:
       response: optional<ResponseWithExample>
       errorStatusCode: list<commons.StatusCode>
       server: list<commons.Server>
+      customCodeSamples:
+        type: list<finalIr.CustomCodeSample>
+        docs: |
+          Populated by `x-fern-code-samples` on a path object.
+          Also migrated from `x-readme.code-samples` if present.
 
   RequestWithExample:
     union:
@@ -270,4 +275,4 @@ types:
 
   BooleanWithExample:
     properties:
-      example: optional<boolean>
+      example: optional<boolean>
diff --git a/packages/cli/cli/package.json b/packages/cli/cli/package.json
@@ -69,7 +69,7 @@
     "@fern-api/yaml-migrations": "workspace:*",
     "@fern-api/yaml-schema": "workspace:*",
     "@fern-fern/fiddle-sdk": "^0.0.386",
-    "@fern-fern/ir-sdk": "0.0.3277",
+    "@fern-fern/ir-sdk": "0.0.3294",
     "ansi-escapes": "^5.0.0",
     "axios": "^0.27.2",
     "boxen": "^7.0.0",

diff --git a/packages/cli/config-management/docs-configuration/package.json b/packages/cli/config-management/docs-configuration/package.json
@@ -29,7 +29,7 @@
   "dependencies": {
     "@fern-api/config-management-commons": "workspace:*",
     "@fern-api/core-utils": "workspace:*",
-    "@fern-api/fdr-sdk": "0.44.0-1-geb2e930",
+    "@fern-api/fdr-sdk": "0.46.1-18-g26596cb",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/task-context": "workspace:*",
     "@fern-fern/docs-config": "0.0.53",

diff --git a/packages/cli/docs-preview/package.json b/packages/cli/docs-preview/package.json
@@ -29,7 +29,7 @@
   "dependencies": {
     "@fern-api/core-utils": "workspace:*",
     "@fern-api/docs-configuration": "workspace:*",
-    "@fern-api/fdr-sdk": "0.44.0-1-geb2e930",
+    "@fern-api/fdr-sdk": "0.46.1-18-g26596cb",
     "@fern-api/fs-utils": "workspace:*",
     "@fern-api/ir-generator": "workspace:*",
     "@fern-api/register": "workspace:*",

diff --git a/packages/cli/docs-preview/src/runPreviewServer.ts b/packages/cli/docs-preview/src/runPreviewServer.ts
@@ -28,7 +28,7 @@ export async function runPreviewServer({
             basePath: ""
         },
         definition: docsDefinition,
-        lightModeEnabled: docsDefinition.config.colorsV3.type !== "dark"
+        lightModeEnabled: docsDefinition.config.colorsV3?.type !== "dark"
     };
 
     app.post("/v2/registry/docs/load-with-url", async (_, res) => {