Amplify-cli: Comment Documentation Schema

[austinamorusocfc]

* Which Category is your question related to? *
API GraphQL Schema
* What AWS Services are you utilizing? *
Appsync Schema
* Provide additional details e.g. code snippets *
How to add comments for documentation on schema for usage in appsync graphiql interface.

# A group of Categories e.g. Moments or Powers
type CategoryGroup @model @searchable @versioned @auth(rules: [
    {allow: groups, groups: ["Admin"]},
    {allow: groups, groupsField: "readGroups", queries: [get, list], mutations: null},
    {allow: groups, groupsField: "writeGroups" mutations: [update, delete], queries: null}
]) {
    id: ID!
    name: String!
    description: String!
    categories: [Category] @connection(name: "GroupCategories")
    language: Language!
    readGroups: [String]!
    writeGroups: [String]!
}

I had the expectation the comment would be reflected in the compiled schema and then viewable in the appsync schema section of the graphiql interface.

[lockevi]

I need this feature too !
I spent a whole day for workaround but failed : (

Can you let me know the schedule for this ?

[VitValchar]

I would like to have this feature as well. It is one of the main features of GraphQL, that you can document your API right in the code, but it is not possible here which makes us use a separate tool for documentation...

[matwerber1]

+1

[clinicalinkgithub]

has there been any movement on this? being able to document is a very importal feature of graphql

[larsvinter]

Any news on this? It really is one of the key features of graphql to be able to document your schema inline...

[VitValchar]

Hi, I was finally able to resolve this issue. The problem is that in older versions of GraphQL, the field description was done by hash mark # this is a comment but in newer versions of GraphQL, it is done by double quotes "this is a comment" over the field/type. ( https://github.com/ardatan/graphql-tools/issues/221#issuecomment-425742915 )

So... amplify api gql-compile is using the specification of a newer GraphQL version, so you have to use the double-quotes. Those are copied over to build/schema.graphql. The AppSync GraphQL server, however, is using an older version of GraphQL that expects the comments to be with hash marks... This results in a funny version mismatch as the description is deployed with the quotes but AppSync does not know what to do with it... I still cannot understand why no one from the Amplify or AWS team did not bring this up sooner.

Anyway, I've created a simple nodejs script that will transform it from one to another. (feel free to use and adjust the script)

const fs = require('fs');
const readline = require('readline');
// path to your build/schema.graphql
const schemaPath = "./build/schema.graphql";

async function process() {
    const fileStream = fs.createReadStream(schemaPath);

    const rl = readline.createInterface({
        input: fileStream,
        crlfDelay: Infinity
    });
    let inComment = false;

    let result = "";

    for await (const line of rl) {
        let matchObj;
        if (matchObj = line.match(/^[ ]*"([^"]+?)"$/)) {
            // resolve single line comment
            result += `# ${matchObj[1]}\n`;
        } else if (matchObj = line.match(/^[ ]*"""(.+?)"""$/)) {
            // resolve multiline comment that is on one line
            result += `# ${matchObj[1]}\n`;
        } else if(line.match(/^[ ]*"""$/)) {
            // set multiline comment start/end
            inComment = !inComment;
        } else if(inComment) {
            // resolve multiline comment
            result += `# ${line.trimStart()}\n`;
        } else {
            // copy whatever other line
            result += line + "\n";
        }
    }

    fs.writeFileSync(schemaPath, result);
    console.log("schema.graphql file comments has been transformed successfully.");
}

process();

it will transform the schema from this

"one line comment"
pk: String!
"""
first line of comment
second line of comment
"""
sk: String!

into this

# one line comment
pk: String!
# first line of comment
# second line of comment
sk: String!

I've created a bash script that runs those commands, so it will transform the descriptions each time I deploy. With this, it works for me pretty fine.

amplify api gql-compile
node transform-docs.js
amplify push --yes --no-gql-override

EDIT: After playing with this a bit more, I found out there are two problems (not sure if they are caused by the old version of GraphQL in AppSync)

1. amplify push will throw you an error if you put the description for enum values (it says something about invalid schema)
2. if you put the description for query/mutation arguments, it will not fail, but will not propagate to the documentation either.

So far I've tried this:

• describing query/mutation works, but describing the query/mutation arguments does not
• describing any custom type and its fields work
• describing any custom input and its fields work
• describing enum works, but describing the enum values does not
  hope you won't have to spend a few hours debugging why the push fails :D

[dtelaroli]

+1

[pshouseGBC]

+1