Fork me on GitHub
#ring-swagger
<
2018-11-13
>
mping13:11:24

@the 2) you can add a description in your api

mping13:11:52

(api
   {:swagger
    {:ui   "/swagger"
     :spec "/swagger.json"
     :data {:info                {:title       "xxx"
                                  :description "yyy"}

mping13:11:37

3) Can’t you define a schema for the route? (defschema Article2 (dissoc Article description))?

mping13:11:40

something like that

thomash13:11:49

@mping 2) I have one big defapi with many nested context. Would you use one api per context?

thomash13:11:56

3) Yeah, that would probably work. I thought I could get away with on-the-fly schemas.

mping13:11:58

that may not work because in swagger, I only see one spot at the top for the description and title

thomash13:11:36

swagger makes a nice section per context. This can have a top-level :description but this text is then used as a default description for the individual routes in the context, not as an "introductory" description.

mping13:11:55

you have summary per route

mping13:11:06

and you also have tags

mping13:11:29

(GET "/rate" []
        :summary "Gets the rate for a given date, aggregated by confirmation date"

mping13:11:41

tags are weird because description is in toplevel, but tags are in each context

thomash13:11:49

yes, this is shown in the route heading (`:summary`), so it's per-route, not per-context.

mping13:11:49

(context "/metrics" []
      :tags ["ui"]
      :coercion :spec

mping13:11:15

(def swagger-api
  (api
   {:swagger
    {:ui   "/swagger"
     :spec "/swagger.json"
     :data {:info                {:title       " services"
                                  :description " services"}
          ...
            :tags                [{:name "processor", :description "migrations and event processor"}
                                  {:name "ui",        :description "ui services"}]

thomash13:11:20

:tags are used as the context title in the api docs.

mping13:11:31

I don’t know any other places other than that

thomash13:11:58

ok, thanks for the effort anyway

mping13:11:19

np, feel free to check the openapi docs, maybe there’s something buried: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md

thomash13:11:37

ah, ok, will do that

ikitommi13:11:37

@the the 3, defschema puts the Schema name, ns and description as meta-data for the Schema. normal dissoc retains the meta-data and the docs are wrong. there are helpers for these in https://github.com/metosin/schema-tools. e..f (-> Article (st/dissoc :description)))

thomash13:11:32

great, thanks 👍

ikitommi13:11:23

also things like st/select-keys, which understand the s/optional-key & s/required-key wrappings.