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.

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

[Question] graphql `Documentation Explorer` #451

Closed
xinshangshangxin opened this issue Aug 20, 2017 · 70 comments

Comments

@xinshangshangxin
Copy link

commented Aug 20, 2017

  • 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

image

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Aug 20, 2017

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

@xinshangshangxin

This comment has been minimized.

Copy link
Author

commented Aug 21, 2017

is any plan to support it?

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Aug 21, 2017

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

@gschier gschier added the Help Wanted label Aug 23, 2017

@alhafoudh

This comment has been minimized.

Copy link

commented Oct 12, 2017

Really need this

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Oct 31, 2017

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

This comment has been minimized.

Copy link

commented Nov 13, 2017

@gschier can you write the guidance here?

@maticrivo

This comment has been minimized.

Copy link

commented Feb 7, 2018

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

This comment has been minimized.

Copy link

commented Feb 7, 2018

@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

This comment has been minimized.

Copy link

commented Feb 7, 2018

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

@alhafoudh

This comment has been minimized.

Copy link

commented Feb 7, 2018

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

This comment has been minimized.

Copy link

commented Feb 8, 2018

@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

This comment has been minimized.

Copy link
Collaborator

commented Feb 8, 2018

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

This comment has been minimized.

Copy link

commented Feb 8, 2018

@gschier
Initial load of GraphiQL:
screenshot from 2018-02-08 08-38-03
After clicking "Docs":
screenshot from 2018-02-08 08-36-23
After writing something in the search box (note that results are type names and field names):
screenshot from 2018-02-08 08-36-38
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).
screenshot from 2018-02-08 08-37-06

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

This comment has been minimized.

Copy link

commented Feb 8, 2018

@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

This comment has been minimized.

Copy link
Collaborator

commented Feb 9, 2018

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

This comment has been minimized.

Copy link

commented Feb 9, 2018

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

This comment has been minimized.

Copy link

commented Feb 10, 2018

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

This comment has been minimized.

Copy link

commented Feb 11, 2018

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

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Feb 11, 2018

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

@maticrivo

This comment has been minimized.

Copy link

commented Feb 11, 2018

@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

This comment has been minimized.

Copy link
Collaborator

commented Feb 11, 2018

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

This comment has been minimized.

Copy link
Collaborator

commented Feb 11, 2018

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

This comment has been minimized.

Copy link

commented Feb 20, 2018

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

@martinek

This comment has been minimized.

Copy link

commented Mar 26, 2018

Is there any progress on this feature?

@maticrivo

This comment has been minimized.

Copy link

commented Mar 26, 2018

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

@EItanya

This comment has been minimized.

Copy link

commented Apr 2, 2018

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.

screen shot 2018-04-02 at 11 29 22 am

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

This comment has been minimized.

Copy link
Collaborator

commented Apr 18, 2018

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

@ilyaklimov

This comment has been minimized.

Copy link

commented Dec 29, 2018

@jimmyn

This comment has been minimized.

Copy link

commented Jan 11, 2019

This would be a very useful feature +1

@ganey

This comment has been minimized.

Copy link

commented Jan 15, 2019

Has this been started yet?

@corbanb

This comment has been minimized.

Copy link

commented Jan 25, 2019

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

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jan 29, 2019

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

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

@guyzmo

This comment has been minimized.

Copy link

commented Mar 2, 2019

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 #1007

@junaidbhura

This comment has been minimized.

Copy link

commented Apr 3, 2019

This feature would complete this app!

@Nta1e

This comment has been minimized.

Copy link

commented Apr 9, 2019

I agree @junaidbhura

@tkvlnk

This comment has been minimized.

Copy link

commented Apr 12, 2019

+1

@tjventurini

This comment has been minimized.

Copy link

commented Apr 25, 2019

+1 😉

@KamilKot95

This comment has been minimized.

Copy link

commented Apr 26, 2019

+1

@XBeg9

This comment has been minimized.

Copy link

commented May 2, 2019

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

@benoit-brulfert

This comment has been minimized.

Copy link

commented May 2, 2019

+1

1 similar comment
@jakeswork

This comment has been minimized.

Copy link

commented May 18, 2019

+1

@KamilKot95

This comment has been minimized.

Copy link

commented May 19, 2019

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

@smare

This comment has been minimized.

Copy link

commented May 22, 2019

+1

1 similar comment
@dyanezr92

This comment has been minimized.

Copy link

commented May 25, 2019

+1

@acao

This comment has been minimized.

Copy link

commented May 25, 2019

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

This comment has been minimized.

Copy link

commented May 28, 2019

+1

@acao

This comment has been minimized.

Copy link

commented May 28, 2019

@gschier here is the working group discussion:

graphql/graphiql#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

This comment has been minimized.

Copy link

commented Jul 4, 2019

+1

3 similar comments
@jarvisuser90

This comment has been minimized.

Copy link

commented Jul 16, 2019

+1

@geraldoramos

This comment has been minimized.

Copy link

commented Jul 22, 2019

+1

@kolbykskk

This comment has been minimized.

Copy link

commented Jul 26, 2019

+1

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Jul 29, 2019

A couple hours into a basic POC for this!

image

@acao

This comment has been minimized.

Copy link

commented Jul 29, 2019

awesome work!

@nicholas-littlelives

This comment has been minimized.

Copy link

commented Aug 1, 2019

You just made it the most perfect GraphQL explorer out there

@gschier

This comment has been minimized.

Copy link
Collaborator

commented Aug 6, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
You can’t perform that action at this time.