From b59c87a783dd8139080f6bf3efc2c32d99bd2ada Mon Sep 17 00:00:00 2001 From: Young Jun Joo Date: Thu, 20 Mar 2025 11:03:09 -0400 Subject: [PATCH] docs: separate tutorials from how-to guides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure documentation to maintain clear boundaries between tutorials and how-to guides following Diátaxis framework principles. Move explanatory content from how-to guides to explanation section and ensure tutorials focus on learning experiences rather than task completion. --- website/docs/tutorial-basics/_category_.json | 2 +- .../docs/tutorial-basics/create-an-api-spec.md | 17 +++++++++-------- .../tutorial-basics/create-an-http-client.md | 16 +++++++++------- .../tutorial-basics/create-an-http-server.md | 17 ++++++++--------- .../tutorial-basics/render-an-open-api-spec.md | 18 ++++++++++-------- 5 files changed, 37 insertions(+), 33 deletions(-) diff --git a/website/docs/tutorial-basics/_category_.json b/website/docs/tutorial-basics/_category_.json index b48dd0c6..b538207e 100644 --- a/website/docs/tutorial-basics/_category_.json +++ b/website/docs/tutorial-basics/_category_.json @@ -3,6 +3,6 @@ "position": 2, "link": { "type": "generated-index", - "description": "Hands-on learning experiences for API specification fundamentals" + "description": "Learning-oriented guides that teach API specification fundamentals through hands-on experience" } } diff --git a/website/docs/tutorial-basics/create-an-api-spec.md b/website/docs/tutorial-basics/create-an-api-spec.md index c2e2a8ba..876c3e91 100644 --- a/website/docs/tutorial-basics/create-an-api-spec.md +++ b/website/docs/tutorial-basics/create-an-api-spec.md @@ -4,12 +4,13 @@ sidebar_position: 1 # Create an API Specification -Use `@api-ts/io-ts-http` to define a standalone **API specification** in TypeScript. +Learn to define a standalone **API specification** in TypeScript using +`@api-ts/io-ts-http`. -## What problem does `io-ts-http` solve? +## Understanding API Contracts -Web services use an [API] as a contract to describe how _clients_ should communicate -with _servers_. +Web services use an [API] as a contract to describe how _clients_ communicate with +_servers_. When a server receives a request from a client, the server needs to answer a few questions before it can begin fulfilling that request: @@ -26,8 +27,8 @@ questions before it can begin fulfilling that request: We'll call the first _type analysis_ and the second _semantic analysis_. -`io-ts-http` lets you define API contracts to an **arbitrary degree of precision**, -removing the burden of semantic analysis from your business logic. +`io-ts-http` enables defining API contracts to an **arbitrary degree of precision**, +removing the burden of semantic analysis from business logic. [api]: https://en.wikipedia.org/wiki/API @@ -41,7 +42,7 @@ $ mkdir api-ts-example $ cd api-ts-example ``` -In your new directory, create a `package.json` file: +In the new directory, create a `package.json` file: ```json package.json { @@ -91,7 +92,7 @@ export const API = apiSpec({ }); ``` -Compile your API specification with: +Compile the API specification with: ``` $ npm run build diff --git a/website/docs/tutorial-basics/create-an-http-client.md b/website/docs/tutorial-basics/create-an-http-client.md index 45b79055..513f05ba 100644 --- a/website/docs/tutorial-basics/create-an-http-client.md +++ b/website/docs/tutorial-basics/create-an-http-client.md @@ -4,14 +4,16 @@ sidebar_position: 3 # Create an HTTP Client +Learn how API specifications enable type-safe communication between clients and servers. + `io-ts-http` API specifications are not coupled to any particular HTTP client. `api-ts` -provides helper libraries that wrap your favorite HTTP client and use the TypeScript -type-checker to ensure type-safe communication with a server implementing an +provides helper libraries that integrate with various HTTP clients and use the +TypeScript type-checker to ensure type-safe communication with a server implementing an `io-ts-http` specification. -## Create a type-safe HTTP Client from an API specification +## Building a type-safe HTTP Client -As before, first edit your `package.json` file to add our new dependencies +As in previous steps, first edit the `package.json` file to add new dependencies (highlighted): ```json package.json focus=10,12,17 @@ -37,7 +39,7 @@ As before, first edit your `package.json` file to add our new dependencies } ``` -And install them by running: +Install them by running: ``` $ npm install @@ -71,14 +73,14 @@ main(); Notice the inferred type of `response.body`. -Compile and run `client.ts` (make sure your server is still running!): +Compile and run `client.ts` (ensure the server is running): ``` $ npm run build $ node ./client.js ``` -You will see output like +The output will be: ``` Response is: Hello, world! diff --git a/website/docs/tutorial-basics/create-an-http-server.md b/website/docs/tutorial-basics/create-an-http-server.md index 5a0a8ae1..8ffaf6c6 100644 --- a/website/docs/tutorial-basics/create-an-http-server.md +++ b/website/docs/tutorial-basics/create-an-http-server.md @@ -4,20 +4,19 @@ sidebar_position: 2 # Create an HTTP Server -An API specification is only useful when clients and servers adhere to its rules. +Learn how API specifications enable type-safe communication between clients and servers. `io-ts-http` API specifications are not coupled to any particular HTTP server. `api-ts` -provides helper libraries that wrap your favorite web server and use the TypeScript -type-checker to ensure your server implementation satisfies the target API -specification. +provides helper libraries that integrate with various web servers and use the TypeScript +type-checker to ensure server implementations satisfy the target API specification. -## Create an HTTP server implementing your API specification +## Building a server with your API specification -We'll use [express] as our underlying web server in this tutorial. +This tutorial uses [express] as the underlying web server. [express]: https://github.com/expressjs/express -First, edit your `package.json` file to add a few new dependencies (highlighted): +First, edit the `package.json` file to add a few new dependencies (highlighted): ```json package.json focus=7,9,13,14 { @@ -39,7 +38,7 @@ First, edit your `package.json` file to add a few new dependencies (highlighted) } ``` -And install them by running: +Install them by running: ``` $ npm install @@ -77,7 +76,7 @@ $ npm run build $ node ./server.js ``` -Finally, submit an HTTP request to your server in a web browser or using a new terminal: +Test the server by submitting an HTTP request in a web browser or using a new terminal: ``` $ curl localhost:3000/hello/world diff --git a/website/docs/tutorial-basics/render-an-open-api-spec.md b/website/docs/tutorial-basics/render-an-open-api-spec.md index 9b6a2f2a..da03cabe 100644 --- a/website/docs/tutorial-basics/render-an-open-api-spec.md +++ b/website/docs/tutorial-basics/render-an-open-api-spec.md @@ -2,19 +2,21 @@ sidebar_position: 4 --- -# Render an OpenAPI specification +# Render an OpenAPI Specification + +Learn how to generate OpenAPI specifications from `io-ts-http` API definitions. An `io-ts-http` specification contains a superset of an [OpenAPI] specification. `api-ts` provides `@api-ts/openapi-generator` to produce an OpenAPI specification from -your `io-ts-http` API specification. This lets you plug your API specification into the -existing OpenAPI ecosystem to HTTP clients for languages other than TypeScript. These -clients won't be as ergonomic or type-safe as an `api-ts` HTTP client. +an `io-ts-http` API specification. This enables integration with the existing OpenAPI +ecosystem to generate HTTP clients for languages other than TypeScript. These clients +won't be as ergonomic or type-safe as an `api-ts` HTTP client. [openapi]: https://www.openapis.org/ -## Use `openapi-generator` +## Working with `openapi-generator` -As before, first edit your `package.json` file to add our new dependencies +As in previous steps, first edit the `package.json` file to add new dependencies (highlighted): ```json package.json focus=15 @@ -41,13 +43,13 @@ As before, first edit your `package.json` file to add our new dependencies } ``` -And install it by running: +Install it by running: ``` $ npm install ``` -The `openapi-generator` requires our TypeScript compiler settings to be specified in a +The `openapi-generator` requires TypeScript compiler settings to be specified in a `tsconfig.json` file, so create one like this: ```json tsconfig.json