servant-swagger: Generate Swagger specification for your servant API.

[ bsd3, library, servant, swagger, web ] [ Propose Tags ]

Please see README.md


[Skip to Readme]

Downloads

Note: This package has metadata revisions in the cabal description newer than included in the tarball. To unpack the package including the revisions, use 'cabal get'.

Versions [RSS] 0.0.0.0, 0.0.0.1, 0.1, 0.1.1, 0.1.2, 1.0, 1.0.1, 1.0.2, 1.0.3, 1.1, 1.1.1, 1.1.2, 1.1.2.1, 1.1.3, 1.1.3.1, 1.1.4, 1.1.5, 1.1.6, 1.1.7, 1.1.7.1, 1.1.8, 1.1.9, 1.1.10, 1.1.11, 1.2, 1.2.1
Dependencies aeson, base (>=4.7 && <5), bytestring, http-media, lens, servant, swagger2 (>=1.0 && <2), text, unordered-containers [details]
License BSD-3-Clause
Copyright David Johnson (c) 2015-2016
Author David Johnson
Maintainer djohnson.m@gmail.com
Revised Revision 2 made by phadej at 2016-07-16T20:40:18Z
Category Web
Home page https://github.com/dmjio/servant-swagger
Bug tracker https://github.com/dmjio/servant-swagger/issues
Source repo head: git clone https://github.com/dmjio/servant-swagger.git
Uploaded by NickolayKudasov at 2015-12-31T00:13:20Z
Distributions Arch:1.2, LTSHaskell:1.2.1, NixOS:1.2, Stackage:1.2.1
Reverse Dependencies 23 direct, 15 indirect [details]
Downloads 30757 total (160 in the last 30 days)
Rating 2.5 (votes: 6) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2015-12-31 [all 1 reports]

Readme for servant-swagger-0.1

[back to package description]

servant-swagger
Hackage

This project converts servant APIs into Swagger 2.0 conforming JSON.


Given the following servant API, servant-swagger generates the following json.

Input

{-# LANGUAGE DataKinds                  #-}
{-# LANGUAGE DeriveGeneric              #-}
{-# LANGUAGE GeneralizedNewtypeDeriving #-}
{-# LANGUAGE OverloadedStrings          #-}
{-# LANGUAGE TypeOperators              #-}
module Main where

import Control.Lens
import Data.Aeson
import qualified Data.ByteString.Lazy.Char8 as BL8
import Data.Proxy
import Data.Swagger
import GHC.Generics
import Servant
import Servant.Swagger

-- Types
data Todo = Todo
  { created     :: Int
  , description :: String
  } deriving (Show, Eq, Generic)

instance ToJSON Todo

newtype TodoId = TodoId String deriving (FromText, Generic)

-- API
type API = "todo" :> Capture "id" TodoId :> Get '[JSON] Todo

-- Swagger Doc
swagDoc :: Swagger
swagDoc = toSwagger (Proxy :: Proxy API)
  & info.infoTitle   .~ "Todo API"
  & info.infoVersion .~ "1.0"
  & info.infoDescription ?~ "This is an API that tests servant-swagger support for a Todo"
  & info.infoLicense ?~ License "MIT" (Just (URL "http://mit.com"))

-- Documentation and annotations
instance ToParamSchema TodoId

instance ToSchema Todo where
  declareNamedSchema proxy = do
    (name, schema) <- genericDeclareNamedSchema defaultSchemaOptions proxy
    return (name, schema
      & schemaDescription ?~ "This is some real Todo right here"
      & schemaExample ?~ toJSON (Todo 100 "get milk"))

-- Main, create swaggger.json
main :: IO ()
main = BL8.writeFile "swagger.json" (encode swagDoc)

Output

{
   "swagger":"2.0",
   "info":{
      "version":"1.0",
      "title":"Todo API",
      "license":{
         "url":"http://mit.com",
         "name":"MIT"
      },
      "description":"This is an API that tests servant-swagger support for a Todo"
   },
   "definitions":{
      "Todo":{
         "example":{
            "created":100,
            "description":"get milk"
         },
         "required":[
            "created",
            "description"
         ],
         "type":"object",
         "description":"This is some real Todo right here",
         "properties":{
            "created":{
               "maximum":9223372036854775807,
               "minimum":-9223372036854775808,
               "type":"integer"
            },
            "description":{
               "type":"string"
            }
         }
      }
   },
   "paths":{
      "/todo/{id}":{
         "get":{
            "responses":{
               "404":{
                  "description":"id not found"
               },
               "200":{
                  "schema":{
                     "$ref":"#/definitions/Todo"
                  },
                  "description":""
               }
            },
            "produces":[
               "application/json"
            ],
            "parameters":[
               {
                  "required":true,
                  "in":"path",
                  "name":"id",
                  "type":"string"
               }
            ]
         }
      }
   }
}

Try it out

All generated swagger specifications can be interactively viewed on Swagger Editor.

Ready-to-use specification can be served as JSON and interactive API documentation can be displayed using Swagger UI.

Many Swagger tools, including server and client code generation for many languages, can be found on Swagger's Tools and Integrations page.

FAQ

  • Q: How is this project different from the swagger package on hackage ?
    • A: This package is based on the latest Swagger 2.0 API

Contributing

We are happy to receive bug reports, fixes, documentation enhancements, and other improvements.

Please report bugs via the github issue tracker.