Updating docs and tutorial (#343)

* Updating docs and tutorial * action.yml updated * folder path * remove Check Markdown links
fern-api · Jul 6, 2022 · 0c29a2b · 0c29a2b
1 parent 4b50686
commit 0c29a2b
Show file tree

Hide file tree

Showing 21 changed files with 77 additions and 85 deletions.
diff --git a/.github/workflows/action.yml b/.github/workflows/action.yml
diff --git a/docs/README.md b/docs/README.md
@@ -2,6 +2,11 @@
 
 > **Fern is a framework for building APIs.** You can think of it as an alternative to OpenAPI (f.k.a Swagger).
 
+<a href="https://www.loom.com/share/c892f4a9fc674c4bb42fb31d395d9ebf">
+    <p>Fern TypeScript Server Tutorial</p>
+    <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/c892f4a9fc674c4bb42fb31d395d9ebf-1657127975624-with-play.gif">
+  </a>
+
 ## How does it work?
 
 ![Overview diagram](assets/diagrams/overview-diagram.png)
@@ -30,12 +35,12 @@ With an API definition, development projects that involve multiple engineers/tea
 
 ## What is a Fern API Definition?
 
-A [**Fern API Definition**](markdown_files/definition.md#what-is-a-fern-api-definition) is a set of YAML files that describe your API.
+A [**Fern API Definition**](_/definition.md#what-is-a-fern-api-definition) is a set of YAML files that describe your API.
 
 ## What are Fern Generators?
 
-[**Generators**](markdown_files/generators.md) convert a Fern API Definition into clients, servers, and documentation.
+[**Generators**](_/generators.md) convert a Fern API Definition into clients, servers, and documentation.
 
 ## How is this different than OpenAPI?
 
-Fern is optimized for [kick-ass codegen](markdown_files/faq.md#_1-how-is-fern-different-than-openapi-fka-swagger).
+Fern is optimized for [kick-ass codegen](_/comparison.md#_1-how-is-fern-different-than-openapi-fka-swagger).
diff --git a/docs/markdown_files/channels.md → docs/_/channels.md b/docs/markdown_files/channels.md → docs/_/channels.md
diff --git a/docs/markdown_files/cli.md → docs/_/cli.md b/docs/markdown_files/cli.md → docs/_/cli.md
diff --git a/docs/_/comparison.md b/docs/_/comparison.md
@@ -0,0 +1,7 @@
+# How is Fern different than OpenAPI (f.k.a Swagger)?
+
+- **Higher-quality code generation**: Fern is more restrictive in what you can model, enabling idiomatic, easy-to-use code generation.
+
+- **Protocol agnostic**: Fern lets you define RESTful services alongside WebSocket subscriptions.
+
+- **Ease of use**: Fern runs code generators remotely and manages publishing packages to registries (e.g., NPM, Maven, PyPI). You get a dependency that you can start using right away.
diff --git a/docs/markdown_files/definition.md → docs/_/definition.md b/docs/markdown_files/definition.md → docs/_/definition.md
diff --git a/docs/markdown_files/errors.md → docs/_/errors.md b/docs/markdown_files/errors.md → docs/_/errors.md
diff --git a/docs/markdown_files/fern-config-json.md → docs/_/fern-config-json.md b/docs/markdown_files/fern-config-json.md → docs/_/fern-config-json.md
diff --git a/docs/markdown_files/fernrc.md → docs/_/fernrc.md b/docs/markdown_files/fernrc.md → docs/_/fernrc.md
diff --git a/docs/markdown_files/generators.md → docs/_/generators.md b/docs/markdown_files/generators.md → docs/_/generators.md
@@ -13,3 +13,15 @@
 |            |                                                                                              |
 |  OpenAPI   |   converts a Fern Definition to an [OpenAPI Spec](https://swagger.io/resources/open-api/)    |  fern add openapi   | <!-- markdown-link-check-disable-line --> [fern-openapi](https://github.com/fern-api/fern-openapi) |
 |            |                                                                                              |
+
+## How does remote code generation work?
+
+Code generators run remotely in the cloud. They take a set of Fern API Definition YAML files, run the generators listed in `.fernrc.yml, and produce generated files as an output. Files can output locally (i.e., seen in the file system of your IDE) or remotely (i.e., in a package manager like NPM, Maven, or PyPI).
+
+### Generating clients
+
+![client generators](../assets/diagrams/frontend-diagram.png)
+
+### Generating servers
+
+![server generators](../assets/diagrams/backend-diagram.png)
diff --git a/docs/markdown_files/ids.md → docs/_/ids.md b/docs/markdown_files/ids.md → docs/_/ids.md
diff --git a/docs/markdown_files/imdb.md → docs/_/imdb.md b/docs/markdown_files/imdb.md → docs/_/imdb.md
@@ -1,9 +1,14 @@
 <!-- markdownlint-disable MD033 -->
 
-# Tutorial: IMDb
+# TypeScript Server Tutorial: IMDb
 
 This guide uses an example API for IMDb (the International Movie Database) that introduces you to using Fern. We'll generate a TypeScript server and a Postman Collection to implement and test our API.
 
+<a href="https://www.loom.com/share/c892f4a9fc674c4bb42fb31d395d9ebf">
+    <p>Video walkthrough</p>
+    <img style="max-width:300px;" src="https://cdn.loom.com/sessions/thumbnails/c892f4a9fc674c4bb42fb31d395d9ebf-1657127975624-with-play.gif">
+  </a>
+
 ## Step 0: Prerequisites
 
 - Install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
@@ -32,6 +37,10 @@ In the root of your backend repo, run:
 fern init
 ```
 
+When it asks you for your `organization`, just write `imdb`.
+
+In the `.fernrc.yml`, let's change the name of our api from `api` to `imdb-api`.
+
 <br>
 <details>
 <summary>What happens:</summary>
@@ -62,7 +71,7 @@ fern add typescript
 <details>
 <summary>What happens:</summary>
 
-`.fernrc.yml` will now list two generators:
+`.fernrc.yml` will now list a generator:
 
 ```diff
  name: api
@@ -80,13 +89,18 @@ fern add typescript
 
 ## Step 4: Run the generator
 
+```bash
+fern generate
+```
+
 In the terminal, you'll see `Published @imdb-fern/imdb-api-server@x.x.x` which we'll add as a dependency. By default, Fern publishes dependencies to a private registry.
 
 ```bash
 # Teach npm about the Fern private registry
 npm config set --location project @imdb-fern:registry https://npm-dev.buildwithfern.com/
 
-npm install @imdb-fern/api-server@x.x.x
+# Your version may be different, but this version will also work
+npm install @imdb-fern/imdb-api-server@0.0.19
 ```
 
 ## Step 5: Implement the server
@@ -95,54 +109,34 @@ We'll create a new file `server.ts` at the root of our project. This will be a s
 
 ```ts
 // server.ts
-import { GetMovieErrorBody, MovieId } from "@imdb-fern/api-server/model";
-import { MoviesService } from "@imdb-fern/api-server/services";
+import { GetMovieErrorBody, MovieId } from "@imdb-fern/imdb-api-server/model";
+import { MoviesService } from "@imdb-fern/imdb-api-server/services";
 import express from "express";
 
 const app = express();
 
 app.use(
   MoviesService.expressMiddleware({
-    // TODO
+    createMovie: () => {
+      return {
+        ok: true,
+        body: MovieId.of("iron-man-3"),
+      };
+    },
+
+    getMovie: () => {
+      return {
+        ok: false,
+        error: GetMovieErrorBody.NotFoundError(),
+      };
+    },
   })
 );
 
 console.log("Listening for requests...");
 app.listen(8080);
 ```
 
-Our IDE will give us red lines indicating that we need to add missing properties.
-
-![server.ts error message](../assets/tutorial/server.ts%20error%20message.png)
-
-You can implement the missing methods, for example:
-
-```diff
- // server.ts
- import express from "express";
- const app = express();
-
- app.use(MoviesService.expressMiddleware({
-+  createMovie: (request) => {
-+    console.log(request);
-+    return {
-+      ok: true,
-+      body: MovieId.of("iron-man-3")
-+    }
-+  },
-
-+  getMovie: () => {
-+    return {
-+      ok: false,
-+      error: GetMovieErrorBody.NotFoundError()
-+    }
-+  }
- }))
-
- console.log("Listening for requests...");
- app.listen(8080);
-```
-
 ## Step 6: Run the server
 
 ```bash
@@ -151,23 +145,29 @@ npx ts-node server.ts
 
 In the terminal, you should see `Listening for requests...`
 
-## Step 6: Add the Postman generator
+## Step 7: Add the Postman generator
+
+In another terminal, let's run:
 
 ```bash
 fern add postman
 fern generate
 ```
 
-In the `api/` folder you'll see `collection.json` that we'll import to Postman.
+In the `api/` folder you'll see `generated-postman.json` that we'll import to Postman.
+
+## Step 8: Hit the server from Postman
+
+Open Postman and File -> Import `api/generated-postman.json`.
 
-## Step 7: Hit the server from Postman
+Select the `createMovie` endpoint and hit `Send`. You should get **`iron-man-3`** back from your server.
 
-Open Postman and File -> Import `api/generated-postman/collection.json`.
+![createMovie-postman](../assets/tutorial/createMovie-postman.png)
 
-Select the `createMovie` endpoint and hit `Send`. You should get a response back from your server **`iron-man-3`**.
+Select the `getMovie` endpoint and hit `Send`. As expected, we get a 404 response back.
 
-![postman-testing](../assets/tutorial/postman-testing.png)
+![getMovie-postman](../assets/tutorial/getMovie-postman.png)
 
-## Step 8: Celebrate
+## Step 9: Celebrate 🎉
 
 You've successfully implemented a simple IMDb server using Fern. You're invited to join our [Discord](https://discord.gg/JkkXumPzcG).
diff --git a/docs/markdown_files/imports.md → docs/_/imports.md b/docs/markdown_files/imports.md → docs/_/imports.md
diff --git a/docs/markdown_files/services.md → docs/_/services.md b/docs/markdown_files/services.md → docs/_/services.md
diff --git a/docs/markdown_files/types.md → docs/_/types.md b/docs/markdown_files/types.md → docs/_/types.md
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -2,15 +2,15 @@
 
 - Getting started
 
-  - [Tutorial: IMDb](markdown_files/imdb.md)
-  - [CLI](markdown_files/cli.md)
+  - [Tutorial: IMDb](_/imdb.md)
+  - [CLI](_/cli.md)
 
 - Concepts
 
-  - [Fern API Definition](markdown_files/definition.md)
-  - [Generators](markdown_files/generators.md)
+  - [Fern API Definition](_/definition.md)
+  - [Generators](_/generators.md)
 
 - Reference
   p
-  - [FAQs](markdown_files/faq.md)
+  - [Comparison with OpenAPI](_/comparison.md)
   - [Join the Discord](https://discord.gg/JkkXumPzcG)
diff --git a/docs/assets/tutorial/createMovie-postman.png b/docs/assets/tutorial/createMovie-postman.png
diff --git a/docs/assets/tutorial/getMovie-postman.png b/docs/assets/tutorial/getMovie-postman.png
diff --git a/docs/assets/tutorial/postman-testing.png b/docs/assets/tutorial/postman-testing.png
diff --git a/docs/assets/tutorial/server.ts error message.png b/docs/assets/tutorial/server.ts error message.png
diff --git a/docs/markdown_files/faq.md b/docs/markdown_files/faq.md