@@ -1,5 +1,36 @@
11{-# LANGUAGE RankNTypes #-}
2−module Data.Swagger.Operation where
2+-- |
3+-- Module: Data.Swagger.Operation
4+-- Copyright: (c) 2015 GetShopTV
5+-- License: BSD3
6+-- Maintainer: Nickolay Kudasov <nickolay@getshoptv.com>
7+-- Stability: experimental
8+--
9+-- Helper traversals and functions for Swagger operations manipulations.
10+-- These might be useful when you already have Swagger specification
11+-- generated by something else.
12+module Data.Swagger.Operation (
13+ -- * Operation traversals
14+ allOperations,
15+ operationsOf,
16+
17+ -- * Manipulation
18+ -- ** Tags
19+ applyTags,
20+ applyTagsFor,
21+
22+ -- ** Responses
23+ setResponse,
24+ setResponseWith,
25+ setResponseFor,
26+ setResponseForWith,
27+
28+ -- ** Paths
29+ prependPath,
30+
31+ -- * Miscellaneous
32+ declareResponse,
33+) where
334
435import Control.Applicative
536import Control.Arrow
@@ -70,6 +101,14 @@ operationsOf sub = paths.itraversed.withIndex.subops
70101 ops = pathItem ^.. template :: [Maybe Operation]
71102 ns = mapMaybe (fmap fst . sequenceA) $ zip [0..] ops
72103
104+-- | Apply tags to all operations and update the global list of tags.
105+--
106+-- @
107+-- 'applyTags' = 'applyTagsFor' 'allOperations'
108+-- @
109+applyTags :: [Tag] -> Swagger -> Swagger
110+applyTags = applyTagsFor allOperations
111+
73112-- | Apply tags to a part of Swagger spec and update the global
74113-- list of tags.
75114applyTagsFor :: Traversal' Swagger Operation -> [Tag] -> Swagger -> Swagger
@@ -87,16 +126,45 @@ declareResponse proxy = do
87126 s <- declareSchemaRef proxy
88127 return (mempty & schema ?~ s)
89128
90−-- | Set response for specified operations.
129+-- | Set response for all operations.
91130-- This will also update global schema definitions.
92131--
93132-- If the response already exists it will be overwritten.
94133--
134+-- @
135+-- 'setResponse' = 'setResponseFor' 'allOperations'
136+-- @
137+--
138+-- Example:
139+--
95140-- >>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
96141-- >>> let res = declareResponse (Proxy :: Proxy Day)
97−-- >>> encode $ api & setResponseFor allOperations 200 res
142+-- >>> encode $ api & setResponse 200 res
98143-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"Day\":{\"format\":\"date\",\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/Day\"},\"description\":\"\"}}}}}}"
99144--
145+-- See also @'setResponseWith'@.
146+setResponse :: HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
147+setResponse = setResponseFor allOperations
148+
149+-- | Set or update response for all operations.
150+-- This will also update global schema definitions.
151+--
152+-- If the response already exists, but it can't be dereferenced (invalid @\$ref@),
153+-- then just the new response is used.
154+--
155+-- @
156+-- 'setResponseWith' = 'setResponseForWith' 'allOperations'
157+-- @
158+--
159+-- See also @'setResponse'@.
160+setResponseWith :: (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
161+setResponseWith = setResponseForWith allOperations
162+
163+-- | Set response for specified operations.
164+-- This will also update global schema definitions.
165+--
166+-- If the response already exists it will be overwritten.
167+--
100168-- See also @'setResponseForWith'@.
101169setResponseFor :: Traversal' Swagger Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
102170setResponseFor ops code dres swag = swag