ring-swagger 2022-03-14 | Slack Archive

Lyderic Dutillieux11:03:39

Hello ! I'd like to generate swagger specs having "field descriptions" (i.e. a description that describes the field in its context, rather than a description in the scope of the standalone schema/type). I've seen the OpenAPI Spec now supports fields (namely :description) aside the :$ref field, for the exact purpose of describing an instance / a role rather than describing a type. Example of what I'd like to generate below :

{:definitions
 {"some-item" {...}
  "some-struct"
  {:type                 "object",
   :properties
   {:primary-item   {:$ref        "#/definitions/some-item"
                     :description "Preferred item under all circumstances"},
    :secondary-item {:$ref        "#/definitions/some-item"
                     :description "Secondary item, because one never knows"}},
   :additionalProperties false}}}

Is this feature supported in ring-swagger yet ? I can't see how to do it (I'm using plumatic schema)

Lyderic Dutillieux11:03:16

Unfortunately, my attempts have been unsuccessful so far, see example below :

(s/defschema some-item
  {:id s/Int})

(s/defschema some-struct
  {:primary-item   (-> some-item
                       (json-schema/describe "Preferred item under all circumstances"))
   :secondary-item (-> some-item
                       (json-schema/describe "Secondary item, because one never knows"))})

(deftest descriptions-are-conflated
  (let [swagger-spec
        (select-keys (swagger/swagger-json
                      {:paths {"/test" {:get {:responses {200 {:schema some-struct}}}}}})
                     [:definitions])]
    (is (= {:definitions
            {"some-item"
             {:description          "Preferred item under all circumstances",
              :type                 "object",
              :properties           {:id {:type "integer", :format "int64"}},
              :additionalProperties false,
              :required             [:id]},
             "some-struct"
             {:type                 "object",
              :properties
              {:primary-item   {:$ref "#/definitions/some-item"},
               :secondary-item {:$ref "#/definitions/some-item"}},
              :additionalProperties false,
              :required             [:primary-item :secondary-item]}}} swagger-spec))))

2022-03-14

Channels