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?

[workshub]

@tolgraven started working on this issue via WorksHub.

[workshub]

An user started working on this issue via WorksHub.

[workshub]

@chandanlal92 started working on this issue via WorksHub.

[workshub]

@ynohtna82nosredna started working on this issue via WorksHub.

[workshub]

A user started working on this issue via WorksHub.

[workshub]

@wizzytod started working on this issue via WorksHub.

[wizzytod]

Hi, @acron0 !

May I suggest using spec-tools to add a description for attach-query's query-spec?
E.g.

(s/def ::droid-query (st/spec {:spec (s/keys :req-un [::id]
                                             :opt [::appears-in])
                               :description "Query for droid"}))

(-> (leona/create)
    (leona/attach-query ::droid-query ::droid droid-resolver)
    ...)

[acron0]

@wizzytod Yes, I would accept PR that connects the dots to make this work

[workshub]

A user started working on this issue via WorksHub.

[workshub]

@ansari691 started working on this issue via WorksHub.

[workshub]

@benjamin-asdf started working on this issue via WorksHub.

[benjamin-asdf]

1. Adding descriptions to objects via metadata on resolver would make sense to me
2. how to do descriptions for fields and args?

;; :leona/description metadata on a resolver or mutation
;; -> add description to the object
(let [job-resolver (fn [c q v])
      job-resolver-with-meta
      (with-meta job-resolver {:leona/description "foo"})
      compiled-schema (-> (leona/create)
                          (leona/attach-query ::job-input :wh/job job-resolver-with-meta)
                          (leona/compile))]
  (-> compiled-schema
      :generated :objects :Job :description))
"foo"


;; Fields and args can also have descriptions, for completeness we would want a way to provide those?
;; not sure if metada conceptually makes sense, but we could add a :descriptions key to compile opts?

(leona/compile
 m
 {:descriptions {:wh/job "a job"
                 :wh.company/name {:fields "company name"
                                   :args "company name arg"}
                 :wh.job/id {:fields "the id of a job"
                             :args "the id of a job"}}})

Update, thoughts:

Instead of args to compile it probably makes more sense that it is another attach- function.
Also for 1) we probably want that on the level of generating, not compiling.