Support for GraphQL

[ArtyomGabeev]

Hi,
Not sure is it a correct place to start the conversation.
Recently Spring team announced support for GraphQL: https://spring.io/projects/spring-graphql

I'm wondering what it will take to provide a support for spring-restdocs project to support documentation for GraphQL.

Couple of questions:

1. is it a good place(repo) to start it.
2. From architecture stand point, what is required if we want to contribute support for graphql?

Thanks,
Artyom

[wilkinsona]

Thanks for the suggestion.

I'm not fundamentally opposed to broadening the project's scope to cover GraphQL (a similar request has been made for message, although it's yet to get much traction), but I'm not sure what it would look like. With a GraphQL schema largely being self-documenting and projects like https://github.com/graphql/graphiql and https://www.npmjs.com/package/graphql-docs, I'm not sure that there's much room to add Spring-specific value for documenting GraphQL APIs.

That said, I may well be overlooking something. What did you have in mind?

[spring-projects-issues]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[cforce]

• Docs would make sense not only in terms of schema's, but of course the schema's shall be part of it.
• GraphiQl is for security reasons (introspection allows to bypass access grants, its a challenge to enforce, or actually its current not guranteed so far i undertand -see Secure Configuration for GraphiQL and Introspection spring-graphql#38 ) no a probate tool to publish (read only) docs for a broader even unauthenticated audience.
• the restdocs MVC use case - to able to "record usage" of requests and practiced and tested api access would make sense for graphql as well. For graphql we can use the rest docs test pattern for queries as exampled (query,mutation, subscription pattern) subset of the schema. The schema offers implicit many not explicit undefined use case by filter, selection etc but per spring test teh docs extension will add description - define by example exactly these possible "use case" with some descriptive context" being defined as spring rest docs context as hint on the test.

[bclozel]

I'm not sure we really need extended Spring for GraphQL support in this project.

Unlike a vanilla REST endpoint, GraphQL APIs are based on a schema with well-defined queries and types (comments included). There are a few tools out there that generate static documentation using only the schema (see graphdoc and graphql-voyager). While they're mostly providing a different view of the schema itself, they're showing a quite complete view of the API already.

I don't think that disabling schema introspection (spring-projects/spring-graphql#38) is really a case for this. IMO it really breaks expectations and doesn't really offer extra security.

GraphQL also supports queries with variables, which are I think a much better base for examples in an API documentation. Spring for GraphQL already supports such queries declared in files when testing your application. At this point, the only missing bit is about including those as code snippets in your asciidoctor documentation.

[wilkinsona]

Thanks, Brian. That strengthens my feeling that there's little value to add here for documenting a GraphQL-based API, particularly given Spring for GraphQL's support for testing with queries declared in files.

@ArtyomGabeev @cforce Given the above, what gaps do you think are left to fill?

[cforce]

I saw the added value in recording the ran queries from the test as query by example.
Of course a user can look into the schema and imagine its as well, but my audience is maybe not always "smart enough :-)
But , yes there are other ways i can achieve the same by coping those examples in some ascidoc manually.

[wilkinsona]

by coping those examples in some ascidoc manually

From what @bclozel was saying, I think you may be able to do this using Asciidoctor's include::[] macro pointing directly at a file in your project's test resources.

[spring-projects-issues]

If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.

[spring-projects-issues]

Closing due to lack of requested feedback. If you would like us to look at this issue, please provide the requested information and we will re-open the issue.