biggedy.
biggedy.2y ago

GraphQL Documentation in Windmill

Hi Team, My company uses GraphQL for our primary API. I have been using it with Windmill to build some common workflows and dashboards for my team but I am wanting to enable them to build their own tools. This got me thinking that I need to provide the team with some documentation so they can explore the API for themselves. For this I was considering spectaql or something similar. - https://github.com/anvilco/spectaql My question to you is would there be a good way to either embed this into a Svelte application or similar so it can appear like any other Windmill application. Would love to hear your thoughts!
GitHub
GitHub - anvilco/spectaql: Autogenerate static GraphQL API document...
Autogenerate static GraphQL API documentation. Contribute to anvilco/spectaql development by creating an account on GitHub.
14 Replies
rubenf
rubenf2y ago
I think you might have a better time using Github ci to generate GitHub pages But maybe this can be packaged into a deno script ? What we already provide is an html component
biggedy.
biggedy.2y ago
Yeah GitHub pages might be a good call. I’ll have a look at that html component and report back what I end up doing. Was really just looking to brainstorm with some clever people. 🤙
rubenf
rubenf2y ago
Btw if you could share your graphql setup, that would be great, I think we do not document that well enough
biggedy.
biggedy.2y ago
Can do, I am caught up this weekend but will do it next week. Do you have any format I should follow? @rubenf apologies for not getting anything out to you yet. I have been setting up our first real application and playing with a few different ways of achieving what we have previously had in a purpose built application. There are some things that would make working with GraphQL in Windmill much better. Currently I am looking into some performance issues and want to see whether it is on my API side before I go making any comments/suggestions. I also have been looking at how others have handled GraphQL support for inspiration, in particular Appsmith and Grafana. As a learn more I’ll put my thoughts here.
rubenf
rubenf2y ago
@biggedy thanks for the feedback. It's possible we would implement graphql and "http rest" jobs that would proxy the requests directly instead of running a script. Do you suspect that would solve the issue ?
biggedy.
biggedy.2y ago
Unsure exactly at this stage Although I would say it could make debugging using the networking tab in the browsers developer tools. I believe some of the areas where others have done a good job it the DX when using a graphql api. Like being have to determine fields based on introspection, or providing a GraphiQL style explorer/editor for building queries.
rubenf
rubenf2y ago
Would you expect to be able to do the graphql calls in the frontend directly ? wouldn't you have issues with CORS?
biggedy.
biggedy.2y ago
Yes I would look to have GraphQL calls in the front end directly. What CORS issues are you suggesting I could/would run into?
rubenf
rubenf2y ago
Have you tried importing https://github.com/jasonkuhrt/graphql-request as a dynamic import ? For instance in your frontend script, doing:
let gql = await import("https://cdn.skypack.dev/graphql-request");
let gql = await import("https://cdn.skypack.dev/graphql-request");
biggedy.
biggedy.2y ago
I am using it like this within a script that is used by the front end: import { gql, GraphQLClient } from "npm:graphql-request@6.0.0";
rubenf
rubenf2y ago
But that's a backend script If you want to use it in the frontend directly Create a frontend script and then do a dynamic import
biggedy.
biggedy.2y ago
Oh yes, sorry. I get what you mean now... What would the benefits of doing it that way be?
rubenf
rubenf2y ago
Then it's done by your browser directly, i thought you found the performance lacking
biggedy.
biggedy.2y ago
Yes it is lacking but I believe it is a combination of things. I will try going this route as well.