feat(docs): re-format multipart fern def (#4922)

multipart Co-authored-by: fern-bot <[email protected]>
fern-api · Oct 15, 2024 · 120b257 · 120b257
1 parent 44a67c1
commit 120b257
Show file tree

Hide file tree

Showing 4 changed files with 79 additions and 23 deletions.
diff --git a/fern/docs.yml b/fern/docs.yml
@@ -132,9 +132,18 @@ navigation:
           - page: Types
             icon: fa-regular fa-shapes
             path: ./pages/api-definition/fern-definition/types.mdx
-          - page: Endpoints
+          - section: Endpoints
             icon: fa-regular fa-plug
             path: ./pages/api-definition/fern-definition/endpoints.mdx
+            contents: 
+              - page: HTTP JSON Endpoints
+                icon: fa-regular fa-display-code
+                path: ./pages/api-definition/fern-definition/endpoints/rest.mdx
+                slug: http
+              - page: Multipart Form Uploads
+                icon: fa-regular fa-file
+                path: ./pages/api-definition/fern-definition/endpoints/multipart.mdx
+                slug: multipart
           - page: Webhooks
             icon: fa-regular fa-webhook
             path: ./pages/api-definition/fern-definition/webhooks.mdx

diff --git a/fern/pages/api-definition/fern-definition/endpoints.mdx b/fern/pages/api-definition/fern-definition/endpoints.mdx
@@ -251,28 +251,6 @@ makes the generated SDKs a bit more idiomatic.
   ```
 </CodeBlock>
 
-## Multipart form uploads
-
-If the request involves uploading a file, use the `file` type
-in your request body.
-
-<CodeBlock title="document.yml">
-```yaml {12}
-service:
-  base-path: /documents
-  auth: false
-  endpoints:
-    uploadDocument:
-      path: /upload
-      method: POST
-      request:
-        name: UploadDocumentRequest
-        body:
-          properties:
-            file: file
-```
-</CodeBlock>
-
 ## Success response
 
 Endpoints can specify a `response`, which is the type of the body that will be

diff --git a/fern/pages/api-definition/fern-definition/endpoints/multipart.mdx b/fern/pages/api-definition/fern-definition/endpoints/multipart.mdx
@@ -0,0 +1,24 @@
+---
+title: Multipart File Upload
+---
+
+Endpoints in Fern are defined underneath the `endpoints` key. If your endpoint request includes file uploads, you can use the `file` type to indicate the request is of a `multiform` content type. The example below demonstrates an endpoint which includes a file in the request body. 
+
+<CodeBlock title="document.yml">
+```yaml {12}
+service:
+  base-path: /documents
+  auth: false
+  endpoints:
+    uploadDocument:
+      path: /upload
+      method: POST
+      request:
+        name: UploadDocumentRequest
+        body:
+          properties:
+            file: file
+```
+</CodeBlock>
+
+Within a given multipart request, a string parameter with `format:binary` will represent an arbitrary file.
diff --git a/fern/pages/api-definition/fern-definition/endpoints/rest.mdx b/fern/pages/api-definition/fern-definition/endpoints/rest.mdx
@@ -0,0 +1,45 @@
+---
+title: HTTP JSON Endpoints
+---
+
+Endpoints in Fern are defined underneath the `endpoints` key. Below is an example of defining 
+a single REST endpoint: 
+
+```yml title="users.yml" maxLines=0
+service: 
+  base-path: /users 
+  auth: false 
+  endpoints: 
+    createUser: 
+      path: /create 
+      method: POST 
+      request: 
+        body: 
+          properties: 
+            userName: string
+```
+
+## Examples
+
+You can provide examples of requests and responses by using the `examples` key.   
+
+```yaml {11-17}
+service:
+  base-path: /users
+  auth: false
+  endpoints:
+    getUser:
+      path: /{userId}
+      path-parameters:
+        userId: string
+      method: GET
+      response: User
+      examples:
+        - path-parameters:
+            userId: alice-user-id
+          response:
+            body:
+              userId: alice-user-id
+              name: Alice
+```
+