docs: generate clients from openapi (#778)

Demonstrate how to use the openapi spec to generate clients in most
languages/frameworks.

#### Migration notes

None

- [ ] The change comes with new or modified tests
- [ ] Hard-to-understand functions have explanatory comments
- [ ] End-user documentation is updated to reflect the change


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Documentation**
- Updated REST API documentation URLs with placeholders for easier
configuration.
- Added information on generating and using OpenAPI clients, including
TypeScript fetch client generation.
- **Bug Fixes**
- Corrected a regular expression in import handling to ensure accurate
replacements.
- **Chores**
- Improved file writing by appending a newline character to JSON
strings.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

typegraph/deno/dev/fix-declarations.ts

@@ -74,7 +74,7 @@ const merged = Array.from(
 // ${relative(denoSdkDir, path)}
 ${
     Deno.readTextFileSync(path)
-      .replaceAll(/import type {.+} from ['"].+\.d.ts['"];/g, (m) => `// ${m}`)
+      .replaceAll(/import type {.+} from ['"].+\.d\.ts['"];/g, (m) => `// ${m}`)
       .replaceAll(/export {.+};/g, (m) => `// ${m}`)
   }
 `;

typegraph/deno/dev/jsr-gen.ts

@@ -52,5 +52,5 @@ Deno.writeTextFileSync(
     },
     null,
     2,
-  ),
+  ) + "\n",
 );

website/docs/reference/rest/index.mdx

@@ -75,10 +75,10 @@ There is no rule in what type of query you should do most of the time as everyth
 
 In other words, depending on what `query_type` (query or mutation), `$param1, $param2, ..` will be defined from the request parameters (GET) or the request body (POST).
 
-- <b>query</b>: Perform a `GET` at
-  `TYPEGATE_URL/TG_NAME/rest/endpoint_name?param1=..&param2=..`
-- <b>mutation</b>: Perform a `POST` at `TYPEGATE_URL/TG_NAME/rest/endpoint_name`
-  with `Content-Type` set as `application/json`
+- <b>query</b>: Perform a `GET` at `{TYPEGATE_URL}/{TG_NAME}
+  /rest/endpoint_name?param1=..&param2=..`
+- <b>mutation</b>: Perform a `POST` at `{TYPEGATE_URL}/{TG_NAME}
+  /rest/endpoint_name` with `Content-Type` set as `application/json`
 
 ```js
 {
@@ -123,6 +123,86 @@ typegraph({ name: "my-typegraph", dynamic: false }, (g) => {
 
 In any case, you can always check the auto-generated documentation of the available endpoints, parameters, output shapes.
 
-You can browse it at `TYPEGATE_URL/TG_NAME/rest`.
+You can browse it at `{TYPEGATE_URL}/{TG_NAME}/rest`.
 
-Or download the OpenAPI spec at `TYPEGATE_URL/TG_NAME/rest/__schema`.
+## OpenAPI clients
+
+In some cases, as your typegraph gets more complicated, you may want to automate the step of writing clients and focus on the actual logic of your application instead.
+
+The OpenAPI spec will be available at `{TYPEGATE_URL}/{TG_NAME}/rest/__schema`, which is very useful considering that there are already a number of tools that enable you to create clients from an existing OpenAPI specification file.
+
+Once you download the specification file for your API, it should look like something like this:
+
+```js
+// {TYPEGATE_URL}/my_awesome_typegraph/rest/__schema
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "my_awesome_typegraph",
+    "license": {
+      "name": "MIT"
+    },
+    "description": "Rest endpoints for typegraph \"my_awesome_typegraph\"",
+    "version": "1.0.0"
+  },
+  "servers": [{ "url": "http://localhost:7890" }],
+  "paths": {
+    // typing each path manually on a custom client can be very tedious as your API grows
+    "/my_awesome_typegraph/rest/get_post": {
+      "get": {
+        "summary": "Perform get_post",
+        "operationId": "get_my_awesome_typegraph_get_post",
+        "responses": { ... }, // you will have various types per response status
+        "parameters": [ ... ]
+      }
+    },
+    "/my_awesome_typegraph/rest/get_post_id": { ... },
+    "/my_awesome_typegraph/rest/read_post": { ... }
+  },
+  "components": { ... }
+}
+```
+
+Here are some of the most used generators:
+
+- Multilang: [OpenAPITools/openapi-generator](https://github.com/OpenAPITools/openapi-generator)
+- Multilang: [@openapitools/openapi-generator-cli](https://www.npmjs.com/package/@openapitools/openapi-generator-cli)
+- Flutter: [openapi_generator](https://pub.dev/packages/openapi_generator)
+
+To keep our setup simple, let us look at [@openapitools/openapi-generator-cli](https://www.npmjs.com/package/@openapitools/openapi-generator-cli),
+which is just a wrapper around [openapi-generator](https://github.com/OpenAPITools/openapi-generator) and will download the appropriate dependencies for you.
+
+First, install the cli globally
+
+```bash
+npm i -g @openapitools/openapi-generator-cli
+```
+
+In this example, let's generate a simple fetch client, you can refer to their official documentation for other generators.
+
+```bash
+openapi-generator-cli generate \
+    -i http://localhost:7890/my_awesome_typegraph/rest/__schema \
+    -g typescript-fetch \
+    -o my-client \
+    --skip-validate-spec
+```
+
+This will generate a `fetch`-based typescript project.
+
+```
+.
++-- apis
+¦    +-- DefaultApi.ts
+¦    +-- index.ts
++-- models
+¦    +-- Either10.ts
+¦    +-- ErrorExtensions.ts
+¦    ...
+¦    +-- GetMyAwesomeTypegraphGetIdentity200Response.ts
+¦    +-- Post.ts
+¦    +-- User.ts
+¦    +-- index.ts
++-- runtime.ts
++-- index.ts
+```