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
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
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. 🤙
Btw if you could share your graphql setup, that would be great, I think we do not document that well enough
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.
@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 ?
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.
Would you expect to be able to do the graphql calls in the frontend directly ?
wouldn't you have issues with CORS?
Yes I would look to have GraphQL calls in the front end directly. What CORS issues are you suggesting I could/would run into?
Have you tried importing
https://github.com/jasonkuhrt/graphql-request as a dynamic import ?
For instance in your frontend script, doing:
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";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
Oh yes, sorry. I get what you mean now... What would the benefits of doing it that way be?
Then it's done by your browser directly, i thought you found the performance lacking
Yes it is lacking but I believe it is a combination of things. I will try going this route as well.