Docblocks disappeared in versions ^1.10.0

[toverux]

Describing the bug

In versions <1.10.0, types generated by the typescript plugin had docblocks with descriptions coming from the API.

After upgrading to latest, those comments are missing from the generated file. I found that this happens since 1.10.0 but nothing in the Releases tab or issues seems to mention any change about this.

My diff looks like this, for hundreds of types:

-/** A connection to a list of items. */
 export type AppletConnection = {
   readonly __typename?: 'AppletConnection',
-  /** Total object count. */
   readonly count: Scalars['Int'],
-  /** Information to aid in pagination. */
   readonly pageInfo: PageInfo,
-  /** Information to aid in pagination. */
   readonly edges: ReadonlyArray<AppletEdge>,
 };

-/** An edge in a connection. */
 export type AppletEdge = {
   readonly __typename?: 'AppletEdge',
-  /** The item at the end of the edge */
   readonly node: Applet,
-  /** A cursor for use in pagination */
   readonly cursor: Scalars['String'],
 };

-/** List of items with pagination. */
 export type AppletPagination = {
   readonly __typename?: 'AppletPagination',
-  /** Total object count. */
   readonly count?: Maybe<Scalars['Int']>,
-  /** Array of objects. */
   readonly items?: Maybe<ReadonlyArray<Maybe<Applet>>>,
-  /** Information to aid in pagination. */
   readonly pageInfo: PaginationInfo,
 };

Of course, I verified that the descriptions are still in the API, and when I'm coming back to versions prior to ^1.10.0, doc blocks are back.

To reproduce

My codegen.yml config file:

schema: "http://localhost:9000/graphql"
generates:
  projects/lib.browser.{redacted}/graphql.generated.ts:
    documents: projects/lib.browser.{redacted}/**/*.graphql
    plugins:
      - add: |
          // /!\ This file is auto-generated by graphql-code-generator. Do not edit by hand.
          // tslint:disable
          // ...line above is mainly for IDE support, see webpack configs where this file is excluded
      - typescript
      - typescript-operations
      - typescript-apollo-angular
    config:
      immutableTypes: true
      scalars:
        MongoID: string
        JSON: any
        Date: string
        JSONObject: '{ [key: string]: any }'
        Success: "'success'"

Dependencies (managed by yarn, lock file confirms latest version is installed) :

{
    "@graphql-codegen/add": "^1.11.0",
    "@graphql-codegen/cli": "^1.11.0",
    "@graphql-codegen/typescript": "^1.11.0",
    "@graphql-codegen/typescript-apollo-angular": "^1.11.0",
    "@graphql-codegen/typescript-operations": "^1.11.0"
}

[leethree]

yes I'm seeing the same issue. all the descriptions are gone.

[anfinil]

I have the same problem.

[koenpunt]

The problem is probably introduced in https://github.com/ardatan/graphql-toolkit, since that library handles the schema loading etc.

[falkenhawk]

also "description" fields are empty now in a generated graphql schema.json

[ardatan]

Could you try with the following canary version? 1.11.3-alpha-aba86640.34

[falkenhawk]

Version 1.11.3-alpha-aba86640.34 does not fix the issue for me.

[ardatan]

@falkenhawk Could you share a reproduction on codesandbox so I can debug?

[dotansimha]

@falkenhawk ?

[falkenhawk]

I'd love to, but I am swamped at the moment... I can share my codegen config file, if that's of any help:

overwrite: true
schema: ${GRAPHQL_URL:http://micro.test/api/graphql}
config:
  namingConvention:
    enumValues: change-case#upperCase
generates:
  ./graphql.schema.json:
    plugins:
      - introspection
  packages/common/gen/graphql.fragments.json:
    plugins:
      - fragment-matcher
  packages/common/src/service.graphql.ts:
    plugins:
      - typescript
hooks:
  afterOneFileWrite:
    - prettier --write

And I have comments attached to my fields in my schema e.g.

type User {
  "Some description for the field"
  something: Boolean
}

Descriptions are missing from both graphql.schema.json (as "description" property of an entity) and service.graphql.ts (as docblock comments, as @toverux reported in the first post):

          {
            "name": "something",
            // in 1.9.1: "description": "Some description for the field",
            "description": "",
            "args": [],
            "type": { (...) },
            "isDeprecated": false,
            "deprecationReason": null
          },

It seems that "descriptions" are not being retrieved properly from an url endpoint. The last version I had this working was 1.9.1, so I am staying on that for the time being.

[dotansimha]

Checked the latest version, and @ardatan added tests in graphql-toolkit.

It seems to work: (tested introspection, schema-ast and typescript plugins)

@falkenhawk @toverux @leethree

Can you please share a reproduction in a sandbox?

[ardatan]

Here is test cases I used from a PR on graphql-toolkit; https://github.com/ardatan/graphql-toolkit/pull/446 This PR doesn't contain any changes on actual code but tests

[falkenhawk]

Thank you for the effort, your reproduction works and tests are passing for a json endpoint. I tried 1.11.3-alpha-19673fd9.101 but descriptions are still gone, when using URL endpoint. Maybe someone could help with setting up a sandbox reproduction with URL endpoint...

[ardatan]

https://github.com/ardatan/graphql-toolkit/blob/master/packages/loaders/url/tests/url-loader.spec.ts We have tests for URL endpoint as well. It has descriptions and a custom schema declaration to be specific.

[falkenhawk]

I looked at the tests, then at the url loader package, and everything looks fine there, when encapsulated. I can only suspect an integration issue, which is not covered by existing tests. E.g. the schema returned from urlloader is a result of makeRemoteExecutableSchema function call, whereas json-file loader uses buildClientSchema function internally - and maybe then generators have troubles handling different structures. My guess might be totally wrong, but I could not find anything else for the time being...

[ardatan]

Could you please share a reproduction repo or codesandbox to get on the same page?

[falkenhawk]

@ardatan https://codesandbox.io/s/solitary-butterfly-yhmfn

in index.js:

const typeDefs = gql`
  """
  All our queries
  """
  type Query {
    "Hello description"
    hello: String
  }
`;

./codegen.yml

overwrite: true
schema: ${GRAPHQL_URL:http://0.0.0.0:4000/}
generates:
  ./graphql.schema.json:
    plugins:
      - introspection
  ./graphql.types.ts:
    plugins:
      - typescript

diff between 1.9.1 and 1.12.1:

./graphql.types.ts

@@ -6,19 +6,15 @@
   Boolean: boolean,
   Int: number,
   Float: number,
-  /** The `Upload` scalar type represents a file upload. */
   Upload: any,
 };

-
 export enum CacheControlScope {
   Public = 'PUBLIC',
   Private = 'PRIVATE'
 }

-/** All our queries */
 export type Query = {
    __typename?: 'Query',
-  /** Hello description */
   hello?: Maybe<Scalars['String']>,
 };

./graphql.schema.json

@@ -9,11 +9,11 @@
       {
         "kind": "OBJECT",
         "name": "Query",
-        "description": "All our queries",
+        "description": "",
         "fields": [
           {
             "name": "hello",
-            "description": "Hello description",
+            "description": "",
             "args": [],
             "type": {
               "kind": "SCALAR",
@@ -871,17 +871,7 @@
       {
         "kind": "SCALAR",
         "name": "Upload",
-        "description": "The `Upload` scalar type represents a file upload.",
-        "fields": null,
-        "inputFields": null,
-        "interfaces": null,
-        "enumValues": null,
-        "possibleTypes": null
-      },
-      {
-        "kind": "SCALAR",
-        "name": "Int",
-        "description": "The `Int` scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.",
+        "description": null,
         "fields": null,
         "inputFields": null,
         "interfaces": null,
@@ -891,37 +881,6 @@
     ],
     "directives": [
       {
-        "name": "cacheControl",
-        "description": "",
-        "locations": [
-          "FIELD_DEFINITION",
-          "OBJECT",
-          "INTERFACE"
-        ],
-        "args": [
-          {
-            "name": "maxAge",
-            "description": "",
-            "type": {
-              "kind": "SCALAR",
-              "name": "Int",
-              "ofType": null
-            },
-            "defaultValue": null
-          },
-          {
-            "name": "scope",
-            "description": "",
-            "type": {
-              "kind": "ENUM",
-              "name": "CacheControlScope",
-              "ofType": null
-            },
-            "defaultValue": null
-          }
-        ]
-      },
-      {
         "name": "skip",
         "description": "Directs the executor to skip this field or fragment when the `if` argument is true.",
         "locations": [

[leethree]

any update on this? I think we have a pretty solid repro here ⬆️

[rzane]

The GraphQL framework I'm using comes with a way to dump the schema to JSON. When I run the codegen against that JSON file, I get docblocks. When I run the codegen against a URL, I don't get docblocks.

This indicates that maybe there is a problem with the introspection query that is being sent to the server? This is the query that is being run when I dump the schema to JSON: https://github.com/absinthe-graphql/absinthe/blob/v1.4.16/priv/graphql/introspection.graphql.

[dotansimha]

I can confirm that this issue happens because of an incorrect configuration codegen passes to graphql-toolkit.

It seems like the url-loader is fetching everything correctly, and building the schema with buildClientSchema as we need to. But something with printSchemaWithDirectives causes description to turn into comments (marked as #)

Then codegen then gets it without it, so the output has it missing.

I'm working on a fix now.

[dotansimha]

@toverux @rzane @leethree @falkenhawk @anfinil @koenpunt Can you please try 1.13.2-alpha-4638c86d.112+4638c86d? It should fix that issue. I tested it with @falkenhawk 's reproduction and it seems to work fine now.

[leethree]

@dotansimha I tried it. The generated schema has documentations now. Thanks!

[dotansimha]

Fixed in v1.13.2