Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update the docs for config generation #566

Merged
merged 5 commits into from
Dec 5, 2024
Merged

docs: update the docs for config generation #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bbea8c2
- update the docs
laststylebender14 Dec 5, 2024
1c659d4
- fix the tabs
laststylebender14 Dec 5, 2024
bbfa51e
fix: update docs
amitksingh1490 Dec 5, 2024
2e5de7b
fix: update docs
amitksingh1490 Dec 5, 2024
c3ce000
fix: update docs
amitksingh1490 Dec 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 29 additions & 21 deletions docs/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
],
Expand Down Expand Up @@ -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"
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
61 changes: 43 additions & 18 deletions docs/config-generation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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 {
Expand Down Expand Up @@ -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": {
Expand All @@ -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:
Expand All @@ -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.

Expand Down Expand Up @@ -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"
}
}
],
Expand All @@ -462,6 +481,7 @@ inputs:
fieldName: "posts"
- proto:
src: "./news.proto"
url: "http://localhost:50051"
preset:
mergeType: 1.0
output:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -974,7 +997,8 @@ curl:
},
{
"proto": {
"src": "./news.proto"
"src": "./news.proto",
"url": "http://localhost:50051"
}
}
],
Expand All @@ -995,6 +1019,7 @@ inputs:
fieldName: "posts"
- proto:
src: "./news.proto"
url: "http://localhost:50051"
schema:
query: "Query"
```
Expand Down
Loading