Find a way to add descriptions to queries and mutations

[acron0]

For documentation purposes, it would be nice if there was a way to add descriptions to queries and mutations so that they appear in GraphQL introspection.

For example, this could be achieved by including a description in the attach-query/attach-mutation function call. A preferable way would either be with docstring or metadata on the handler.

[devurandom]

Would it be possible to access the docstrings of resolver functions for this? Fields could get their description from the s/def docstring: https://dev.clojure.org/jira/browse/CLJ-1965

[acron0]

That would definitely be ideal...if specs had docstrings :/ Right now I think we'll have to make do with expanding the attach fns so they can optionally accept a description.

[devurandom]

Alex said that docstrings are still on the list of things to be included in spec.alpha2. I personally would just wait for that, instead of adding a bandaid that then has to be maintained indefinitely.

[Wryhder]

Right now I think we'll have to make do with expanding the attach fns so they can optionally accept a description.

@acron0 I would like to work on this, if no one else already is.

[acron0]

@Wryhder Yep, please do 👍

[kevinmungai]

Hi, I hope I have understood what the issue is but what if the "docstrings" were pulled from the resolvers for example:

(defmacro doc-string
  [symbol]
  `(:doc (meta (var ~symbol))))

Then this would be called by a function

(defn attach-doc-string
  [function]
  (let [doc (doc-string function)]
    (if doc
      doc
     "please add a description")))

I am not sure where to put this description yet, I went ahead and naively attached it to the :result-spec. Some guidance would assist me on where to put it.

(defn attach-query
  "Adds a query resolver into the provided pre-compiled data structure"
  #_([m resolver]
     ;; TODO infer specs from fdef
     )
  ([m query-spec results-spec resolver]
   {:pre [(s/valid? ::pre-compiled-data m)]}
   (-> m
       (update :specs   conj results-spec)
       (update :queries assoc results-spec {:resolver resolver
                                            :query-spec query-spec
                                            :description (util/attach-doc-string resolver)}))))

This strategy may help when the specs are later inferred.

[acron0]

@kevinmungai Yes, this is basically 50% of the solution! The description then needs to be pushed into the schema as a kind of post-generation step.

[kevinmungai]

@acron0 Thanksl for the feedback. It will take me sometime before I get a working solution.

[kevinmungai]

Hi @acron0, I am having a bit of an issue. I have tried to generate a simple schema from the example on the README but I just can't.

the expected

a lacinia schema should be generated using this

(spec/def ::query-spec map?)
(spec/def ::response map?)

(-> (leona/create)
                  (leona/attach-query ::query-spec ::response (fn [context query value]))
                  (leona/compile))

what am experiencing

Execution error (IllegalArgumentException) at leona.schema/transform (schema.clj:110).
Don't know how to create ISeq from: clojure.lang.Keyword

what I have tried

I have tried to run the tests of leona but I get
Execution error (IllegalArgumentException) at leona.schema/transform (schema.clj:110).
Don't know how to create ISeq from: clojure.lang.Keyword

To be honest this is my first time trying to contribute to open source, I think I might be the issue but after 2 days of trying I have decided to ask for help. Thank you for your time.

[workshub]

If you successfully complete this Issue via WorskHub there's a $75 reward available.
Start work via WorksHub Issue Details page.

[workshub]

@umitduran started working on this issue via WorksHub.

[acron0]

@kevinmungai Don't worry :) Leona is still young, and there is still some holes in the documentation so that could be the problem here. What version of Leona are you using? And you say running the tests gives you a IllegalArgumentException?