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

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

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

something like that

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

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

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

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.

you have summary per route

and you also have tags

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

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

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

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

(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"}]

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

yep

I don’t know any other places other than that

ok, thanks for the effort anyway

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

ah, ok, will do that

@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)))

great, thanks 👍

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