diff --git a/hledger-api/hledger-api.cabal b/hledger-api/hledger-api.cabal
index 2ba2f0f71..ae8f3976a 100644
--- a/hledger-api/hledger-api.cabal
+++ b/hledger-api/hledger-api.cabal
@@ -27,7 +27,8 @@ cabal-version:  >= 1.10
 
 extra-source-files:
     CHANGES
-    examples/01-accounts.html
+    examples/01.html
+    examples/02.html
 
 source-repository head
   type: git
@@ -42,12 +43,16 @@ executable hledger-api
     , hledger          == 0.27
     , base             >= 4 && < 5
     , aeson
+    , bytestring
     , containers
     , Decimal
     , docopt
     , either
+    , lens
     , safe
     , servant-server
+    , servant-swagger
+    , swagger2
     , text
     , transformers
     , wai
diff --git a/hledger-api/hledger-api.hs b/hledger-api/hledger-api.hs
index 09ae4910c..b390fd1c1 100644
--- a/hledger-api/hledger-api.hs
+++ b/hledger-api/hledger-api.hs
@@ -11,21 +11,25 @@
 
 module Main where
 
+import           Control.Lens ((&), (.~), (?~))
 import           Control.Monad
 import           Control.Monad.IO.Class
 import           Control.Monad.Trans.Either
 import           Control.Monad.Trans.Reader
 import           Data.Aeson
+import qualified Data.ByteString.Lazy.Char8 as BL8
 import           Data.Decimal
 import qualified Data.Map as M
 import           Data.Monoid
 import           Data.Proxy
+import           Data.Swagger
 import           Data.Text hiding (map,reverse)
 import           GHC.Generics
 import           Network.Wai as Wai
 import           Network.Wai.Handler.Warp as Warp
 import           Safe
 import           Servant
+import           Servant.Swagger
 import           System.Console.Docopt
 import           System.Environment (getArgs)
 import           System.Exit
@@ -37,6 +41,7 @@ import Hledger.Cli hiding (Reader, version)
 
 version="0.27.98"
 
+-- https://github.com/docopt/docopt.hs#readme
 doc :: Docopt
 doc = [docopt|
 hledger-api 0.27.98
@@ -45,6 +50,9 @@ Serves hledger data and reports as a JSON web API.
 
 Usage:
   hledger-api [options]
+    start API server
+  hledger-api --swagger
+    print API docs in Swagger 2.0 format
   hledger-api --version
   hledger-api --help
 
@@ -63,6 +71,7 @@ main = do
   args <- getArgs >>= parseArgsOrExit doc
   when (isPresent args (longOption "help")) $ exitWithUsage doc
   when (isPresent args (longOption "version")) $ putStrLn version >> exitSuccess
+  when (isPresent args (longOption "swagger")) $ BL8.putStrLn (encode swaggerDoc) >> exitSuccess
   let defp = "8001"
   p <- case readMay $ getArgWithDefault args defp (longOption "port") of
         Nothing -> exitWithUsage doc
@@ -87,6 +96,7 @@ type HledgerApi =
   :<|> "commodities"  :> Get '[JSON] [Commodity]
   :<|> "accounts"     :> Get '[JSON] [Account]
   :<|> "accounttransactions" :> Capture "acct" AccountName :> Get '[JSON] AccountTransactionsReport
+  -- :<|> "swagger"      :> Get '[JSON] Swagger
   :<|> Raw
 
 hledgerApiApp :: FilePath -> Journal -> Wai.Application
@@ -103,6 +113,7 @@ hledgerApiApp staticdir j = Servant.serve api server
       :<|> commoditiesH
       :<|> accountsH
       :<|> accounttransactionsH
+      -- :<|> swaggerH
       :<|> serveDirectory staticdir
       where
         accountnamesH = return $ journalAccountNames j
@@ -120,6 +131,7 @@ hledgerApiApp staticdir j = Servant.serve api server
             q = Hledger.Query.Any --filterQuery (not . queryIsDepth) $ queryFromOpts d ropts'
             thisacctq = Acct $ accountNameToAccountRegex a -- includes subs
           return $ accountTransactionsReport ropts j q thisacctq
+        -- swaggerH = return swaggerDoc
 
 instance ToJSON ClearedStatus where toJSON = genericToJSON defaultOptions -- avoiding https://github.com/bos/aeson/issues/290
 instance ToJSON GenericSourcePos where toJSON = genericToJSON defaultOptions
@@ -160,3 +172,35 @@ instance ToJSON Account where
     ,"asubs"        .= toJSON (map toJSON $ asubs a)
     ]
 instance ToJSON AccountTransactionsReport where toJSON = genericToJSON defaultOptions
+
+-- swagger api doc
+
+swaggerDoc :: Swagger
+swaggerDoc = toSwagger (Proxy :: Proxy HledgerApi)
+  & info.infoTitle   .~ "hledger API"
+  & info.infoVersion .~ "0.0.0.1"
+  & info.infoDescription ?~ "This is the API provided by hledger-api for reading hledger data"
+  & info.infoLicense ?~ License "GPLv3+" (Nothing)
+
+-- instance ToSchema Swagger
+instance ToSchema ClearedStatus
+instance ToSchema GenericSourcePos
+instance ToSchema Decimal
+ where
+  declareNamedSchema _proxy = pure (Just "Decimal", schema)
+   where
+     schema = mempty
+       & schemaType .~ SwaggerNumber
+       & schemaExample ?~ toJSON (100 :: Decimal)
+instance ToSchema Amount
+instance ToSchema AmountStyle
+instance ToSchema Side
+instance ToSchema DigitGroupStyle
+instance ToSchema MixedAmount
+instance ToSchema Price
+instance ToSchema MarketPrice
+instance ToSchema PostingType
+instance ToSchema Posting
+instance ToSchema Transaction
+instance ToSchema Account
+-- instance ToSchema AccountTransactionsReport
diff --git a/hledger-api/package.yaml b/hledger-api/package.yaml
index ef0e44023..8b63324a8 100644
--- a/hledger-api/package.yaml
+++ b/hledger-api/package.yaml
@@ -154,12 +154,16 @@ executables:
       - hledger          == 0.27
       - base             >= 4 && < 5
       - aeson
+      - bytestring
       - containers
       - Decimal
       - docopt
       - either
+      - lens
       - safe
       - servant-server
+      - servant-swagger
+      - swagger2
       - text
       - transformers
       - wai