A DSL for documenting Compojure routes using Swagger spec
JavaScript CSS Clojure
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
example
src/swag
test/swag/test
.gitignore
.travis.yml
CHANGES.md
README.md
project.clj

README.md

Swag

Build Status

A DSL for documenting Compojure routes using Swagger spec, such a spec can be viewed (and invoked) via Swagger UI.

Usage

[swag "0.2.7"]

Model and routes

Models are composits custom data types passed into routes:

; custom data types https://github.com/wordnik/swagger-core/wiki/Datatypes
(defmodel action :operates-on :string :src :string :actions {:type "Actions"})

Routes are decorated compojure routes:

(defroutes- actions {:path "/actions" :description "Adhoc actions managment"}

  ; here we use the custom action model (the model schema will reflect that).
  (POST- "/action" [& ^:action action] {:nickname "addActions" :summary "Adds an actions set"}
         {:status 200 :body (str "got action " action)})

  ;; ...

  ; note the use of :errorResponses
  (DELETE- "/action/:id" [^:int id] {:nickname "deleteActions" :summary "Deletes an action set" 
                                     :errorResponses (errors {:bad-req "Missing action"})}
        {:status 200 :body (str "got id " id)}))

Conversions:

Conversions can be defined on a group of routes, in this case all /actions routes that accept a composit object with a :type field will get it converted to a keyword (v is an implicit params value passed to the conversion function):

(defc "/actions" [:type] (keyword v))

For docs see:

Limitations

  • The DSL wraps Compojure and supports vector based destructing:
 
  ; will not work because swag expects a vector of args with metadata types
  [:as {{id :id} :params}]

  ; however the following is compatible 
  [^:int id]
  
  ; will also work
  [& :sometype foo]
 
  • Parameter attributes aren't supported yet this will be resolved in next release.

License

Copyright © 2013 Ronen Narkis

Distributed under the Eclipse Public License, the same as Clojure.