docs: update the docs for config generation (#566)

--------- Co-authored-by: amit <amitksingh1490@gmail.com>
tailcallhq · Dec 5, 2024 · c148af2 · c148af2
1 parent 95b4e33
commit c148af2
Show file tree

Hide file tree

Showing 2 changed files with 72 additions and 39 deletions.
diff --git a/docs/cli.md b/docs/cli.md
@@ -181,7 +181,8 @@ To generate a Tailcall GraphQL configuration, provide a configuration file to th
     },
     {
       "proto": {
-        "src": "./news.proto"
+        "src": "./news.proto",
+        "url": "http://127.0.0.1:8080/rpc"
       }
     }
   ],
@@ -232,6 +233,7 @@ inputs:
       fieldName: "createPost"
   - proto:
       src: "./news.proto"
+      url: "http://127.0.0.1:8080/rpc"
 output:
   path: "./output.graphql"
   format: "graphQL"
@@ -374,25 +376,31 @@ The `inputs` section specifies the sources from which the GraphQL configuration
     }
     ```
 
-4.  **Proto:** For protobuf files, specify the path to the proto file (`src`).
-
-    <Tabs>
-      <TabItem value="json" label="JSON">
-      ```json
-      {
-        "proto": {
-          "src": "./path/to/file.proto"
-        }
-      }
-      ```
-      </TabItem>
-      <TabItem value="yml" label="YML">
-      ```yml
-      - proto:
-          src: "./news.proto"
-      ```
-      </TabItem>
-    </Tabs>
+4.  **Proto:**
+
+    - Specify the **path to the proto file** (`src`) to help Tailcall create a schema and understand the gRPC methods to call when a field is queried.
+    - Specify the **gRPC URL** (`url`) where the gRPC service is hosted.
+    - Include a **boolean parameter** `connectRPC` (optional). If set to `true`, the proto file will be used to generate the schema, but the communication between Tailcall and the upstream will happen using the [Connect-RPC protocol](https://connectrpc.com/docs/protocol/).
+
+        <Tabs>
+          <TabItem value="json" label="JSON">
+          ```json
+          {
+            "proto": {
+              "src": "./path/to/file.proto",
+              "url": "http://127.0.0.1:8080/rpc"
+            }
+          }
+          ```
+          </TabItem>
+          <TabItem value="yml" label="YML">
+          ```yml
+          - proto:
+              src: "./news.proto"
+              url: "http://127.0.0.1:8080/rpc"
+          ```
+          </TabItem>
+        </Tabs>
 
 ### Output
 
@@ -573,7 +581,7 @@ preset:
    }
    ```
 
-   By leveraging field names to derive type names, the schema becomes more intuitive and aligned with the data it represents, enhancing overall readability and understanding.
+   By leveraging field names to derive type names, the schema becomes more intuitive and aligned with the data it represents, enhancing overall readability and understanding. You can learn more about config autogen [here](./config-generation.md).
 
 ### LLM
 

diff --git a/docs/config-generation.md b/docs/config-generation.md
@@ -134,16 +134,21 @@ Tailcall simplifies GraphQL schema generation from REST APIs, supporting various
     - **format**: Specifies the output format as GraphQL (in above example, it's `graphQL`).
 
 To generate the GraphQL configuration run following command
+
 <Tabs>
-<TabItem value="json" label="JSON Config Format">
-`bash
-    tailcall gen ./config.json
-    `
-</TabItem>
 <TabItem value="yml" label="YML Config Format">
-`bash
-    tailcall gen ./config.yml
-    `
+
+```bash
+tailcall gen ./config.yml
+```
+
+</TabItem>
+<TabItem value="json" label="JSON Config Format">
+
+```bash
+tailcall gen ./config.json
+```
+
 </TabItem>
 </Tabs>
 **Schema**: Specifies the name of the Query operation type, which is `Query` in this example.
@@ -288,7 +293,7 @@ tailcall gen ./config.json
   </TabItem>
   </Tabs>
 
-**Schema**: Specifies the operation type. In this example, it's a `Mutation` operation with the name `Mutation`.
+Generated Configuration looks like following.
 
 ```graphql showLineNumbers title="Generated GraphQL Configuration"
 schema @server @upstream {
@@ -342,6 +347,13 @@ Tailcall simplifies the process of generating GraphQL schemas from gRPC. By spec
                   "src": "./news.proto",
                   "url": "http://localhost:50051"
                 }
+              },
+              {
+                "proto": {
+                  "src": "./news.proto",
+                  "url": "http://localhost:8080/news.NewsService/",
+                  "connectRPC": true
+                }
               }
             ],
             "preset": {
@@ -365,6 +377,10 @@ Tailcall simplifies the process of generating GraphQL schemas from gRPC. By spec
           - proto:
             src: "./news.proto"
             url: "http://localhost:50051"
+          - proto:
+            src: "./news.proto"
+            url: "http://localhost:8080/news.NewsService/"
+            connectRPC: true
         preset:
           mergeType: 1.0
         output:
@@ -382,6 +398,8 @@ Let's understand the above configuration file.
 **Proto**: Defines the path to the proto file that the configuration interacts with.
 
 - **src**: Specifies the path to the proto file (`./news.proto` in this example).
+- **url**: Specifies the url on which gRPC service is hosted. (`http://localhost:50051` in this example).
+- **connectRPC**: An optional flag indicating whether Tailcall should generate [`Connect-RPC`](https://connectrpc.com/docs/protocol/) compatible configuration.
 
 **Preset**: We've applied only one tuning parameter for the configuration. let's understand it in short.
 
@@ -436,7 +454,8 @@ Here is an example configuration that demonstrates how to set up a hybrid integr
     },
     {
       "proto": {
-        "src": "./news.proto"
+        "src": "./news.proto",
+        "url": "http://localhost:50051"
       }
     }
   ],
@@ -462,6 +481,7 @@ inputs:
       fieldName: "posts"
   - proto:
       src: "./news.proto"
+      url: "http://localhost:50051"
 preset:
   mergeType: 1.0
 output:
@@ -495,20 +515,23 @@ Let's understand the above configuration file.
 - **format**: Specifies the output format as GraphQL (in above example, it's `graphQL`).
 
 To generate the GraphQL configuration run following command
+
 <Tabs>
+<TabItem value="yml" label="YML Config Format">
+
+```bash
+tailcall gen ./config.yml
+```
+
+</TabItem>
 <TabItem value="json" label="JSON Config Format">
 
 ```bash
 tailcall gen ./config.json
 ```
 
-  </TabItem>
-  <TabItem value="yml" label="YML Config Format">
-    ```bash
-    tailcall gen ./config.yml
-    ```
-  </TabItem>
-  </Tabs>
+</TabItem>
+</Tabs>
 **Schema**: Specifies the name of the Query operation type, which is `Query` in this example.
 
 ```graphql showLineNumbers
@@ -974,7 +997,8 @@ curl:
     },
     {
       "proto": {
-        "src": "./news.proto"
+        "src": "./news.proto",
+        "url": "http://localhost:50051"
       }
     }
   ],
@@ -995,6 +1019,7 @@ inputs:
       fieldName: "posts"
   - proto:
       src: "./news.proto"
+      url: "http://localhost:50051"
 schema:
   query: "Query"
 ```