fix invalid swagger json

README.md

@@ -12,15 +12,19 @@ integration tests, and joint line coverage.
 ## Running
 
 ```bash
-clojure -X:run
+script/server [port]
 ```
 
-The server listens on port `3000` by default; set `PORT` to change it:
+The server listens on port `3000` by default; pass a port argument or set `PORT` to change it
+(the argument wins):
 
 ```bash
-PORT=8080 clojure -X:run
+script/server 8080
+PORT=8080 script/server
 ```
 
+This is a thin wrapper around `clojure -X:run`, which also honors `PORT`.
+
 Or build and run the container:
 
 ```bash

script/server

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# Start the server. Usage: script/server [port]
+# The port defaults to $PORT, then 3000.
+set -euo pipefail
+cd "$(dirname "$0")/.."
+
+port=${1:-${PORT:-3000}}
+if [[ ! $port =~ ^[0-9]+$ ]] || (( port < 1 || port > 65535 )); then
+  echo "usage: script/server [port]  (port must be 1-65535, got '$port')" >&2
+  exit 2
+fi
+
+PORT=$port exec clojure -X:run

src/tbd/core.clj

@@ -10,6 +10,17 @@
             [tbd.health.routes :as health]
             [tbd.math.routes :as math]))
 
+(defn- swagger-handler
+  "reitit emits `\"definitions\": null` when no route declares a schema, which
+  violates the Swagger 2.0 schema (must be an object) and makes validators reject the spec."
+  []
+  (let [handler (swagger/create-swagger-handler)]
+    (fn [req]
+      (let [resp (handler req)]
+        (cond-> resp
+          (and (map? (:body resp)) (nil? (:definitions (:body resp))))
+          (update :body dissoc :definitions))))))
+
 ;; Each logical group (health, users, orders, ...) owns a `tbd.<group>.routes`
 ;; namespace that returns its own route subtree; they're concatenated here.
 (def router
@@ -17,7 +28,7 @@
     [["/swagger.json"
       {:get {:no-doc true
              :swagger {:info {:title "tbd API" :version "1.0.0"}}
-             :handler (swagger/create-swagger-handler)}}]
+             :handler (swagger-handler)}}]
      ["/" {:get {:no-doc true
                  :handler (fn [_req]
                             {:status 200

test/tbd/core_test.clj

@@ -22,7 +22,9 @@
 (deftest swagger-spec-test
   (let [resp (request :get "/swagger.json")]
     (is (= 200 (:status resp)))
-    (is (re-find #"/api/ping" (slurp (:body resp))))))
+    (is (re-find #"/api/ping" (slurp (:body resp))))
+    (is (not (re-find #"\"definitions\":null" (slurp (:body (request :get "/swagger.json")))))
+        "a null `definitions` makes the spec invalid Swagger 2.0")))
 
 (deftest unknown-route-test
   (is (= 404 (:status (request :get "/nope")))))