git.iko.soy/typeable/openapi3
on master help sign in
Add simpler helpers and structure docs for Data.Swagger.Operation
a791a74Nickolay Kudasov
src/Data/Swagger/Operation.hs+71−3
compare with master
unifiedsplit
@@ -1,5 +1,36 @@
1{-# LANGUAGE RankNTypes #-}
1{-# LANGUAGE RankNTypes #-}
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.
2−module Data.Swagger.Operation where
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
3
34
4import Control.Applicative
35import Control.Applicative
5import Control.Arrow
36import Control.Arrow
@@ -70,6 +101,14 @@ operationsOf sub = paths.itraversed.withIndex.subops
70 ops = pathItem ^.. template :: [Maybe Operation]
101 ops = pathItem ^.. template :: [Maybe Operation]
71 ns = mapMaybe (fmap fst . sequenceA) $ zip [0..] ops
102 ns = mapMaybe (fmap fst . sequenceA) $ zip [0..] ops
72
103
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+
73-- | Apply tags to a part of Swagger spec and update the global
112-- | Apply tags to a part of Swagger spec and update the global
74-- list of tags.
113-- list of tags.
75applyTagsFor :: Traversal' Swagger Operation -> [Tag] -> Swagger -> Swagger
114applyTagsFor :: Traversal' Swagger Operation -> [Tag] -> Swagger -> Swagger
@@ -87,16 +126,45 @@ declareResponse proxy = do
87 s <- declareSchemaRef proxy
126 s <- declareSchemaRef proxy
88 return (mempty & schema ?~ s)
127 return (mempty & schema ?~ s)
89
128
90−-- | Set response for specified operations.
129+-- | Set response for all operations.
91-- This will also update global schema definitions.
130-- This will also update global schema definitions.
92--
131--
93-- If the response already exists it will be overwritten.
132-- If the response already exists it will be overwritten.
94--
133--
134+-- @
135+-- 'setResponse' = 'setResponseFor' 'allOperations'
136+-- @
137+--
138+-- Example:
139+--
95-- >>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
140-- >>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
96-- >>> let res = declareResponse (Proxy :: Proxy Day)
141-- >>> let res = declareResponse (Proxy :: Proxy Day)
97−-- >>> encode $ api & setResponseFor allOperations 200 res
142+-- >>> encode $ api & setResponse 200 res
98-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"Day\":{\"format\":\"date\",\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/Day\"},\"description\":\"\"}}}}}}"
143-- "{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"definitions\":{\"Day\":{\"format\":\"date\",\"type\":\"string\"}},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/Day\"},\"description\":\"\"}}}}}}"
99--
144--
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+--
100-- See also @'setResponseForWith'@.
168-- See also @'setResponseForWith'@.
101setResponseFor :: Traversal' Swagger Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
169setResponseFor :: Traversal' Swagger Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
102setResponseFor ops code dres swag = swag
170setResponseFor ops code dres swag = swag