Ben KraftandGitHub
2eba9a2c30
## Summary: In this commit I reorganize much of our documentation into a new `docs` directory, where there will hopefully be more room to grow and to organize things in a user-friendly way. There's almost no net-new documentation, although of course it's a great time to review it anyway. In particular: - I moved the documentation for the `genqlient.yaml` config file into an example file instead of GoDoc (which now just points to the example file); I think this will be a lot clearer for casual users. - I moved the documentation for the `@genqlient` directive out of GoDoc and into a GraphQL schema file (since while it's a comment it's all real syntax), likewise, and made the `GenqlientDirective` type private (since there's now nothing useful to do with it). - I moved `DESIGN.md` and the logo into `docs/` (just to keep the toplevel a bit cleaner), and separated the Contributing section of the README into `docs/CONTRIBUTING.md` (which github will automatically link on various issue and PR pages). This leaves it so that: - README.md is the only documentation at the toplevel (and will become just the high-level introduction as I add more user docs to `docs/`) - GoDoc is only documentation for if you want to call genqlient programmatically (which is fairly limited as the API surface is quite small: it's now just Main, Generate, and Config, plus a constructor, a single method, and a bunch of fields on the latter) In future commits, I'll add some more new documentation to the `docs` directory. Issue: https://github.com/Khan/genqlient/issues/26 ## Test plan: make check (and read the docs) Author: benjaminjkraft Reviewers: jvoll, benjaminjkraft, aberkan, dnerdy, MiguelCastillo, mahtabsabet Required Reviewers: Approved By: jvoll Checks: ✅ Lint, ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Test (1.17), ✅ Test (1.16), ✅ Test (1.15), ✅ Test (1.14), ✅ Lint Pull Request URL: https://github.com/Khan/genqlient/pull/84
117 lines
4.9 KiB
YAML
117 lines
4.9 KiB
YAML
# genqlient.yaml is genqlient's configuration file. This genqlient.yaml is an
|
|
# example; use `go run github.com/Khan/genqlient --init` to generate a simple
|
|
# starting point.
|
|
|
|
# The filename with the GraphQL schema (in SDL format), relative to
|
|
# genqlient.yaml.
|
|
schema: schema.graphql
|
|
|
|
# Filenames or globs with the operations for which to generate code, relative
|
|
# to genqlient.yaml.
|
|
#
|
|
# These may be .graphql files, containing the queries in SDL format, or
|
|
# Go files, in which case any string-literal starting with (optional
|
|
# whitespace and) the string "# @genqlient" will be extracted as a query.
|
|
operations:
|
|
- genqlient.graphql
|
|
- "pkg/*.go"
|
|
|
|
# The filename to which to write the generated code, relative to
|
|
# genqlient.yaml.
|
|
generated: generated/genqlient.go
|
|
|
|
# The package name for the output code; defaults to the directory name of
|
|
# the generated-code file.
|
|
package: mygenerated
|
|
|
|
# If set, a file at this path (relative to genqlient.yaml) will be generated
|
|
# containing the exact operations that genqlient will send to the server.
|
|
#
|
|
# This is useful for systems which require queries to be explicitly
|
|
# safelisted (e.g. [1]), especially for cases like queries involving fragments
|
|
# where it may not exactly match the input queries, or for other static
|
|
# analysis. The JSON is an object of the form
|
|
# {"operations": [{
|
|
# "operationName": "operationname",
|
|
# "query": "query operationName { ... }",
|
|
# "sourceLocation": "myqueriesfile.graphql",
|
|
# }]}
|
|
# Keys may be added in the future.
|
|
#
|
|
# By default, no such file is written.
|
|
#
|
|
# [1] https://www.apollographql.com/docs/studio/operation-registry/
|
|
export_operations: operations.json
|
|
|
|
# Set to the fully-qualified name of a Go type which generated helpers
|
|
# should accept and use as the context.Context for HTTP requests.
|
|
#
|
|
# Defaults to context.Context; set to "-" to omit context entirely (i.e.
|
|
# use context.Background()). Must be a type which implements
|
|
# context.Context.
|
|
context_type: context.Context
|
|
|
|
# If set, a function to get a graphql.Client, perhaps from the context.
|
|
# By default, the client must be passed explicitly to each genqlient
|
|
# generated query-helper.
|
|
#
|
|
# This is useful if you have a shared client, either a global, or
|
|
# available from context, and don't want to pass it explicitly. In this
|
|
# case the signature of the genqlient-generated helpers will omit the
|
|
# `graphql.Context` and they will call this function instead.
|
|
#
|
|
# Must be the fully-qualified name of a function which accepts a context
|
|
# (of the type configured as ContextType (above), which defaults to
|
|
# `context.Context`, or a function of no arguments if ContextType is set
|
|
# to the empty string) and returns (graphql.Client, error). If the
|
|
# client-getter returns an error, the helper will return the error
|
|
# without making a query.
|
|
client_getter: "github.com/you/yourpkg.GetClient"
|
|
|
|
# A map from GraphQL type name to Go fully-qualified type name to override
|
|
# the Go type genqlient will use for this GraphQL type.
|
|
#
|
|
# This is primarily used for custom scalars, or to map builtin scalars to
|
|
# a nonstandard type. By default, builtin scalars are mapped to the
|
|
# obvious Go types (String and ID to string, Int to int, Float to float64,
|
|
# and Boolean to bool), but this setting will extend or override those
|
|
# mappings.
|
|
#
|
|
# genqlient does not validate these types in any way; they must define
|
|
# whatever logic is needed (MarshalJSON/UnmarshalJSON or JSON tags) to
|
|
# convert to/from JSON. For this reason, it's not recommended to use this
|
|
# setting to map object, interface, or union types, because nothing
|
|
# guarantees that the fields requested in the query match those present in
|
|
# the Go type.
|
|
#
|
|
# To get equivalent behavior in just one query, use @genqlient(bind: ...);
|
|
# see genqlient_directive.graphql for more details.
|
|
bindings:
|
|
# To bind a scalar:
|
|
DateTime:
|
|
# The fully-qualified name of the Go type to which to bind. For example:
|
|
# time.Time
|
|
# map[string]interface{}
|
|
# github.com/you/yourpkg/subpkg.MyType
|
|
type: time.Time
|
|
|
|
# To bind an object type:
|
|
MyType:
|
|
type: github.com/you/yourpkg.GoType
|
|
# If set, a GraphQL selection which must exactly match the fields
|
|
# requested whenever this type is used. Only applies if the GraphQL type
|
|
# is a composite output type (object, interface, or union).
|
|
#
|
|
# This is useful if Type is a struct whose UnmarshalJSON or other methods
|
|
# expect that you requested certain fields. For example, given the below
|
|
# config, genqlient will reject if you make a query
|
|
# { fieldOfMytype { id title } }
|
|
# The fields must match exactly, including the ordering: "{ name id }"
|
|
# will be rejected. But the arguments and directives, if any, need not
|
|
# match.
|
|
#
|
|
# TODO(benkraft): Also add ExpectIncludesFields and ExpectSubsetOfFields,
|
|
# or something, if you want to say, for example, that you have to request
|
|
# certain fields but others are optional.
|
|
expect_exact_fields: "{ id name }"
|