Insomnia: [Question] graphql `Documentation Explorer`

[xinshangshangxin]

• Insomnia Version: 5.7.11 (5.7.11.978)
• Operating System: mac 10.12.5 (16F73)

Details

where I can see Documentation Explorer like graphiQL

[gschier]

There is no way to see GraphQL documentation in Insomnia right now.

[xinshangshangxin]

is any plan to support it?

[gschier]

No plans yet, but maybe in the future. It seems like it could be very useful.

[alhafoudh]

Really need this

[gschier]

I don't have time to work on this but I could provide guidance if someone else wanted to contribute a PR for it.

[alhafoudh]

@gschier can you write the guidance here?

[maticrivo]

if no one has started working on this i want to give it a try.
@gschier you think you are free to guide on where on the UI should i add this? I have a few ideas, but i would love your input

[alhafoudh]

@maticrivo thats good to hear :) what about putting it inside the code (graphql query) editor to the right like graphiql does it. it should be collapsible maybe?

[maticrivo]

Yes. I was thinking something like a tab next to the query but a collapsible sidebar sounds even better

[alhafoudh]

It should be visible all the time. Tab is a context switch for a developer.
I would be also nice to remember the path user viewing the documentation in when selecting between requests.

[maticrivo]

@alhafoudh Sounds good. I'll start working on a collapsible sidebar next to the query editor and work our way from there with features we want

[gschier]

Can someone post a screenshot or two of the GraphiQL doc browser for reference?

My initial thought is that a sidebar in the query editor makes the most sense. Maybe it could move to a popup or a modal if the pane is not wide enough for it to be useful? Wherever it ends up, it should be usable in large and small windows, as well as in the vertical (side-by-side) and horizontal layouts.

If you get the documentation browser working (the hard part 😄) in a column then I can help refine the UI and make it responsive.

[mandx]

@gschier
Initial load of GraphiQL:

After clicking "Docs":

After writing something in the search box (note that results are type names and field names):

After clicking on a type name, it shows its name at the top, the description after the search box (and below that, for object types, the list of fields).

f I had a criticism of the GraphiQL Docs explorer it would be how much clicking is required to navigate the schema tree, most of the time when constructing a query, I need to see the docs for several levels at once, but I waste a lot of time going up and down the type tree, and then alternating between the query editor (keyboard) and the docs eplorer (mouse). My point with this would be that maybe this is an opportunity to create a better docs explorer (maybe with a different interaction paradigm) instead of just cloning it for Insomnia.

[maticrivo]

@gschier im planning to start working on it next week.. it shouldnt be that hard.
From what i checked the insomnia "fetch schema" and graphiql document explorer are both doing the same query to the server under the hood so it should only be a matter of displaying the schema and not only storing it for autocomplete and validation.

[gschier]

Thanks for the screenshots and feedback @mandx!

Unless someone already has an idea for how to improve the interaction it's probably best to keep it simple at first, then improve things later on based on user feedback. My first thought would be to add a hotkey (eg. ctrl+click) within the editor (like IDEs do) to pop open the docs for a specific type. Feel free to comment with your ideas below 😄

@maticrivo yes, I agree. The schema information is already there, we just need a UI for it.

[mickdekkers]

Just a thought, but an actual tree view of the types could be useful to reduce the number of clicks required to navigate the documentation. Perhaps it'd be best to contribute things like these to the graphiql project itself though, so that all projects that make use of it can be improved.

[mandx]

Here's another approach: https://www.graphqlbin.com/RVIn The schema docs/explorer is the green sideways tab to the right.

Repo link: https://github.com/graphcool/graphql-playground

[maticrivo]

@gschier should this be developed as a plugin? or as something built-in to insomnia?

[gschier]

@maticrivo, definitely built-in since it's so closely related to a major core feature.

[maticrivo]

@gschier what approach should i go with? the one like in the graphqlbin posted by @mandx or the one in the graphiql screenshots posted by @mandx?

[gschier]

At first glance the second one looks more productive but it also seems harder to implement.

I think it would be good to get a simple proof of concept going first, then discuss the user experience and layout in more detail as the next step.

[gschier]

I'll leave it up to you to decide what the first iteration looks like. Just remember to keep it simple and plan for it to change 🥇

I'll be here if you need anything 😄

[kapouille]

Here's a suggestion for a first iteration : how about a popup help when you hover over the suggestion drop down items?

[martinek]

Is there any progress on this feature?

[maticrivo]

Sorry, I have been very busy at work lately. I will try and resume work this week or the next

[EItanya]

I realize I am a little late to the game here, but I would just like to say that graphcool's playground has expanded on Graphiql's explorer, and in my opinion made it much better.

You can play around with the schema explorer here: https://legacy.graphqlbin.com/RVIn

It is much prettier, and much more easily navigated. It fixes what @mandx said above about having to do too much clicking in graphiql. It takes a multi-layered approach as shown above which allows much better understanding of the query structure.

@maticrivo I would love to get involved with this anyway I can, I think that graphcool's implementation has a lot of benefits. You said you've been very busy and I would be more than happy to do what I can.

This is really the final feature that stops me from being able to use insomnia for everything graphql development related.

[gschier]

Anyone start on this yet? I'd like to start work on it soon if not.

[Leandros]

Would love to see this!

[BrendanBall]

I somehow only found out now that insomnia has added graphql support.
@EItanya, at first the graphql playground with the layered approach looks good, but I've already had trouble with it when you get to 4-5 or more layers at which point it's completely ontop of the query editor so I can't edit the query and have the explorer open at the same time. I would say if you limit the number of layers that it shows to maybe 3 (maybe make this a configurable property), then it should work pretty nicely.

I agree that getting out the same functionality as current alternatives like graphiql out is step 1.
After that, one feature that the explorer really needs is to right click on a type and copy all field names to paste into the query editor. Currently working with types with many fields is horrible, as even with autocomplete, you still have to manually insert every field into your query. Obviously it being graphql, you don't always want all fields, so it could be fancier with maybe a select box next to each field and then an insert selected fields into query button.

So has anyone started on this? Looks like everyone has gotten busy on other things. Not having the explorer is pretty much a deal breaker to use insomnia for graphql, so if no one is working on this I can maybe try help out.

[gschier]

I have not started on it yet (even though I said I would). I couldn't come up with a good place to put the UI.

[gschier]

Haven't started on a docs explorer yet but I _am_ basically done with "hover docs".

[krailler]

+1

[aheissenberger]

+1

[eamigo86]

+1

[VladimirDosen]

+1

[yuritoledo]

+1

[galileomd]

another vote for schema explorer!

[grafael]

I think this feature could be something like a tree where you can expand or collapse showing the types and attributes.

[bryancross]

Chiming in from GitHub, yes please :) . A tree view would be ideal, but any sort of meaningful presentation would be a huge help!

[kryptn]

+1

[ilyaklimov]

+1

[eamigo86]

Any forecast of a release with this new functionality?

[ilyaklimov]

Yes, thanks.

сб, 29 дек. 2018 г., 13:09 Ernesto Pérez Amigo [email protected]:

Any forecast of a release with this new functionality?

—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
https://github.com/getinsomnia/insomnia/issues/451#issuecomment-450481548,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AGvE3C4DuhfTaBXy7Ex_YcWoXBGqivRNks5u9z9agaJpZM4O8nFn
.

[jimmyn]

This would be a very useful feature +1

[ganey]

Has this been started yet?

[corbanb]

I vote https://github.com/imolorhe/altair and Insomnia do a gql mutation and make us all happy campers.

[gschier]

Has not been started yet, no. Currently working on other things.

Woah @corbanb, altair looks really slick! Some nice inspiration there.

[guyzmo]

Also, to add my 2 cents to this discussion, it would be neat to display the schema in a way that would be similar to displaying swagger/openapi documentation cf https://github.com/getinsomnia/insomnia/issues/1007

[junaidbhura]

This feature would complete this app!

[Nta1e]

I agree @junaidbhura

[tkvlnk]

+1

[tjventurini]

+1 :wink:

[KamilKot95]

+1

[XBeg9]

+1 can't use insomnia for Graphql, until we get explorer for schema.

[benoit-brulfert]

+1

[jakeswork]

+1

[KamilKot95]

It is useless without docs. It will be perfect with.

[smare]

+1

[dyanezr92]

+1

[acao]

I'm a maintainer of graphiql. All our components are exported. graphql-playground imports some of our DocExplorer components to acheive this. Unfortunately we can't expose the styles via styled components, but with graphiql 1.x we will! Join our working group for graphiql and tasks like this could be a lot easier. I'm a big fan of Insomnia and would love this feature as well!

[sebmor]

+1

[acao]

@gschier here is the working group discussion:

https://github.com/graphql/graphiql/issues/829

I'll be sure to invite you or someone you'd prefer from your project to the next WG meeting, which is due soon. We also have codemirror-graphql and it's dependents under our domain, which I see you are using

[matmunn]

+1

[jarvisuser90]

+1

[geraldoramos]

+1

[kolbykskk]

+1

[gschier]

A couple hours into a basic POC for this!

[acao]

awesome work!

[nicholas-littlelives]

You just made it the most perfect GraphQL explorer out there

[gschier]

This is live now! https://insomnia.rest/changelog/6.6.0