Añadir descripciones y documentar los campos de GraphQL

Una de las mayores dificultades de usar una API es disponer una documentación clara y completa para conocer los endpoints que dispone, los parámetros que acepta, sus tipos y las estructuras de datos devueltas, los códigos de estado y error que devuelve asi como un entorno para proba la API en ejecución. Una API REST no ofrece ningún soporte para suplir sus carencias de documentar toda esta información y se suele recurrir a alguna otra herramienta como Swagger.

En GraphQL mucho de esto se proporciona en la definición del esquema de GraphQL donde quedan definidos los tipos de los que se compone el esquema, las propiedades de esos tipos así como el tipos de datos de esas propiedades, por otro lado el editor GraphiQL ofrece un pequeño IDE para probar la API con asistencia de código y ver su documentación.

Uno de los problemas de la documentación es que sea inconsistente con la realidad del código, la ventaja de documentar la API en el propio código fuente es que es más fácil actualizar la documentación y que el código y a documentación sea consistente en todo momento. Otra utilidad común con el paso del tiempo y nuevas versiones es documentar en el propio esquema los campos cuyo uso está desaconsejado u es obsoleto con la directiva @deprecated.

Aunque la propia información del esquema ya es una gran ayuda para poder utilizar una API de GraphQL par mayor documentación es necesario añadir una descripción más detallada o una aclaración sobre una propiedad. En el propio esquema de GraphQL a los tipos y propiedades se les puede añadir una descripción.

Para añadir descripciones basta con incluir un comentario en la linea anterior al tipo o propiedad en el propio esquema de la API. Esto es lo único necesario para que en GrapiQL las descripciones añadidas aparezcan al explorar el esquema de la API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

...

# The Magazine entity type.
type Magazine {
    # The identifier.
    id: Long
    # The magazine name.
    name: String
    # The number of pages that magazine has.
    pages: Long
}

...

Una vez añadidos los comentarios tanto en el IDE de GraphiQL como realizando introspección se obtienen las descripciones de los campos.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

query Publications {
  publications {    
    ... on Book {
      __typename
      id      
      title
      date
    }
    ... on Magazine {
      __typename
      id
      name
      pages
    }
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
 book: __type(name: "Magazine") {
   name
   
   fields(includeDeprecated: true) {
     name
     description
     isDeprecated
     type {
       name
       kind
     }
   }
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

{
  "data": {
    "book": {
      "name": "Magazine",
      "fields": [
        {
          "name": "id",
          "description": "The identifier.",
          "isDeprecated": false,
          "type": {
            "name": "Long",
            "kind": "SCALAR"
          }
        },
        {
          "name": "name",
          "description": "The magazine name.",
          "isDeprecated": false,
          "type": {
            "name": "String",
            "kind": "SCALAR"
          }
        },
        {
          "name": "pages",
          "description": "The number of pages that magazine has.",
          "isDeprecated": false,
          "type": {
            "name": "Long",
            "kind": "SCALAR"
          }
        },
        {
          "name": "old",
          "description": "",
          "isDeprecated": true,
          "type": {
            "name": "String",
            "kind": "SCALAR"
          }
        }
      ]
    }
  }
}

Poner nombres semánticos y significativos a los tipos y propiedades es una gran ayuda, para mayor detalle, aclaraciones y puntualizaciones están las descripciones que se pueden añadir en GraphQL.