Swagger implementation for Ring using Prismatic Schema for data models and coercion.

• Provides functions to create both Swagger Resource listing and Api declarations.
• Schema extensions for modelling, coersion and JSON Schema generation
• Does not cover how the routes and models are collected from web apps (and by so should be compatible with all Ring-based libraries)
  • Provides a Map-based interface for higher level web libs to create Swagger Spec out of their route definitions

[metosin/ring-swagger "0.8.7"]

• Compojure-Api for Compojure
• fnhouse-swagger for fnhouse

If your favourite web lib doesn't have an client adapter, you could write an it yourself. Here's howto:

1. Define routes to serve the ring.swagger.core/api-listing and ring.swagger.core/api-declaration
2. Create a route-collector to collect the route metadata.
3. Optionally define a route for the swagger-ui
4. Publish it.
5. List your adapter here

The building blocks for creating Web Schemas are found in package ring.swagger.schema. All schemas must be declared by defmodel, which set up the needed meta-data. Otherwise, it's just a normal Schema.

• Vectors, Sets and Maps can be used as containers
  • Maps are presented as Complex Types and References. Model references are resolved automatically.
  • Nested maps are transformed automatically into flat maps with generated child references.

Ring-swagger utilizes Schema coercions for transforming the input data into vanilla Clojure and back. There are two modes for coersions: json and query.

• numbers -> Long or Double
• string -> Keyword
• string -> java.util.Date, org.joda.time.DateTime or org.joda.time.LocalDate
• vectors -> Sets

extends the json-coersion with the following transformations:

• string -> Long
• string -> Double
• string -> Boolean

(require '[ring.swagger.schema :refer :all])
(require '[schema.core :as s])

(defmodel Country {:code (s/enum :fi :sv)
                   :name String})
; #'user/Country

(defmodel Customer {:id Long
                    :name String
                    (s/optional-key :address) {:street String
                                               :country Country}})
; #'user/Customer

Country
; {:code (enum :fi :sv), :name java.lang.String}

Customer
; {:id java.lang.Long, :name java.lang.String, #schema.core.OptionalKey{:k :address} {:street java.lang.String, :country {:code (enum :fi :sv), :name java.lang.String}}}

CustomerAddress
; {:street java.lang.String, :country {:code (enum :fi :sv), :name java.lang.String}}

(def matti {:id 1 :name "Matti Mallikas"})
(def finland {:code :fi :name "Finland"})

(coerce Customer matti)
; {:name "Matti Mallikas", :id 1}

(coerce Customer (assoc matti :address {:street "Leipätie 1" :country finland}))
; {:address {:country {:name "Finland", :code :fi}, :street "Leipätie 1"}, :name "Matti Mallikas", :id 1}

(coerce Customer {:id 007})
; #schema.utils.ErrorContainer{:error {:name missing-required-key}}

(coerce! Customer {:id 007})
; ExceptionInfo throw+: {:type :ring.swagger.schema/validation, :error {:name missing-required-key}}  ring.swagger.schema/coerce! (schema.clj:89)

JSON Schema generation is implemented using multimethods. You can register your own schema types by installing new methods to the multimethods.

(require '[ring.swagger.core :as swagger])
(require '[schema.core :as s])
(defmethod swagger/json-type-class s/Maybe [e] (swagger/->json (:schema e)))

(require '[ring.swagger.core :as swagger])
(require '[schema.core :as s])
(defmethod swagger/json-type s/Any [_] {:type "string"})

• support for vanilla schemas (removes the Var-resolving)
• consumes
• authorization
• files
• non-json produces & consumes
• full spec

Pull Requests welcome. Please run the tests (lein midje) and make sure they pass before you submit one.

Copyright © 2014 Metosin Oy

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