Release xiana 0.5.0-rc6 (#270)

Co-authored-by: Iain Wood <[email protected]>

.gitignore

@@ -121,3 +121,4 @@ pom.xml.asc
 .clj-kondo/*
 !.clj-kondo/config.edn
 *.iml
+doc/swagger.org

CHANGELOG.md

@@ -1,5 +1,13 @@
 ## Unreleased
 
+## 0.5.0-rc6
+
+- kebab camel interceptor for all request type #263
+- dev/reset migratus #264
+- Add swagger documentation #266
+- Feature/swagger toplevel description #268
+- Bump hiccup/hiccup to version 2.0.0-RC2 #269
+
 ## 0.5.0-rc5
 
 - Bump info.sunng/ring-jetty9-adapter ring adapter library

doc/swagger.md

@@ -0,0 +1,68 @@
+# Swagger documentation
+
+## config
+
+You need to specify your swagger.json and swagger-ui endpoints at the config file
+
+    :xiana/swagger         {:uri-path "/swagger/swagger.json"
+                            :path :swagger.json
+                            :data {:coercion (reitit.coercion.malli/create
+                                              {:error-keys #{:coercion :in :schema :value :errors :humanized}
+                                               :compile malli.util/closed-schema
+                                               :strip-extra-keys true
+                                               :default-values true
+                                               :options nil})
+                                   :middleware [reitit.swagger/swagger-feature]
+                                   ;;; This is toplevel info for your project swagger-ui page
+                                   :info {:title "Your Project Title goes HERE"
+                                          :description "Some description"
+                                          :version "0.1"}}}
+    :xiana/swagger-ui      {:uri-path "/swagger/swagger-ui"}
+
+## System config
+
+To add the `/swagger/swagger.json` and `/swagger/swagger-ui` endpoints you need
+to add **xiana.swagger/add-swagger-endpoints** to your system configuration before
+the **routes/reset**
+
+    (defn ->system
+      [app-cfg]
+      (-> (config/config app-cfg)
+          ...
+          xsw/add-swagger-endpoints
+          routes/reset
+          ...
+          ws/start))
+
+## Routes creations
+
+### Description
+
+If you want a description for your endpoint on the **swagger-ui** page, include it in your route in the map
+associated with the swagger key as below:
+
+    ["/users" {:get {:description "This is the description that will appear on swagger-ui under this endpoint"
+                     :action #'users/get-all-users}}]
+
+### Parameters
+
+At the moment **xiana.swagger** will not generate all the data for the endpoints
+automaticaly. You need to specify whether the endpoint needs :body :path or :query
+parameters and you need to specify those parameters. The good news is that if
+you already have a malli schema for your endpoint, you can reuse that.
+
+At the moment **xiana.swagger** will ONLY work with malli schemas!
+
+    ["/users" {:post {:action #'users/add-users
+                      :schema UsersAddReqPayload
+                      :parameters {:body UsersAddReqPayload}
+                      :description "This is the description that will appear on swagger-ui under this endpoint"}}]
+
+If you don't already use a schema you can specify it inline like this:
+
+    ["/users" {:post {:action #'users/add-users
+                      :parameters {:body [:map {:closed true}
+                                          [:name string?]
+                                          [:age int?]]}
+                      :description "This is the description that will appear on swagger-ui under this endpoint"}}]
+

release.edn

@@ -1,4 +1,4 @@
 {:group-id "com.flexiana"
  :artifact-id "framework"
- :version "0.5.0-rc5"
+ :version "0.5.0-rc6"
  :scm-url "https://github.com/Flexiana/framework"}