fix: OpenAPI :description belongs at Response level, not Media Type

also, support singular :example in addition to :examples
metosin · Sep 16, 2024 · 610586f · 610586f
1 parent 5a81142
commit 610586f
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 14 deletions.
diff --git a/examples/openapi/src/example/server.clj b/examples/openapi/src/example/server.clj
@@ -50,8 +50,8 @@
 
        ["/pizza"
         {:get {:summary "Fetch a pizza | Multiple content-types, multiple examples"
-               :responses {200 {:content {"application/json" {:description "Fetch a pizza as json"
-                                                              :schema [:map
+               :responses {200 {:description "Fetch a pizza as json or EDN"
+                                :content {"application/json" {:schema [:map
                                                                        [:color :keyword]
                                                                        [:pineapple :boolean]]
                                                               :examples {:white {:description "White pizza with pineapple"
@@ -60,8 +60,7 @@
                                                                          :red {:description "Red pizza"
                                                                                :value {:color :red
                                                                                        :pineapple false}}}}
-                                          "application/edn" {:description "Fetch a pizza as edn"
-                                                             :schema [:map
+                                          "application/edn" {:schema [:map
                                                                       [:color :keyword]
                                                                       [:pineapple :boolean]]
                                                              :examples {:red {:description "Red pizza with pineapple"
@@ -71,20 +70,19 @@
                            :body {:color :red
                                   :pineapple true}})}
          :post {:summary "Create a pizza | Multiple content-types, multiple examples"
-                :request {:content {"application/json" {:description "Create a pizza using json"
-                                                        :schema [:map
+                :request {:description "Create a pizza using json or EDN"
+                          :content {"application/json" {:schema [:map
                                                                  [:color :keyword]
                                                                  [:pineapple :boolean]]
                                                         :examples {:purple {:value {:color :purple
                                                                                     :pineapple false}}}}
-                                    "application/edn" {:description "Create a pizza using EDN"
-                                                       :schema [:map
+                                    "application/edn" {:schema [:map
                                                                 [:color :keyword]
                                                                 [:pineapple :boolean]]
                                                        :examples {:purple {:value (pr-str {:color :purple
                                                                                            :pineapple false})}}}}}
-                :responses {200 {:content {:default {:description "Success"
-                                                     :schema [:map [:success :boolean]]
+                :responses {200 {:description "Success"
+                                 :content {:default {:schema [:map [:success :boolean]]
                                                      :example {:success true}}}}}
                 :handler (fn [_request]
                            {:status 200
@@ -114,9 +112,11 @@
                                    :email "[email protected]"}]})}}]
 
        ["/account"
-        {:get {:summary "Fetch an account | Recursive schemas using malli registry"
+        {:get {:summary "Fetch an account | Recursive schemas using malli registry, link to external docs"
                :parameters {:query #'AccountId}
                :responses {200 {:content {:default {:schema #'Account}}}}
+               :openapi {:externalDocs {:description "The reitit repository"
+                                        :url "https://github.com/metosin/reitit"}}
                :handler (fn [_request]
                           {:status 200
                            :body {:bank "MiniBank"

diff --git a/modules/reitit-openapi/src/reitit/openapi.clj b/modules/reitit-openapi/src/reitit/openapi.clj
@@ -83,7 +83,7 @@
         ->content (fn [data schema]
                     (merge
                      {:schema schema}
-                     (select-keys data [:description :examples])
+                     (select-keys data [:example :examples])
                      (:openapi data)))
         ->schema-object (fn [model opts]
                           (let [result (coercion/-get-model-apidocs
@@ -112,7 +112,7 @@
                       (select-keys schema [:description])))
              (into []))})
      (when body
-       ;; body uses a single schema to describe every :requestBody
+       ;; :body uses a single schema to describe every :requestBody
        ;; the schema-object transformer should be able to transform into distinct content-types
        {:requestBody {:content (into {}
                                      (map (fn [content-type]
@@ -123,7 +123,7 @@
                                      request-content-types)}})
 
      (when request
-       ;; request allow to different :requestBody per content-type
+       ;; :request allows different :requestBody per content-type
        {:requestBody
         (merge
          (select-keys request [:description])