swagger2-2.5: Swagger 2.0 data model

MaintainerNickolay Kudasov <nickolay@getshoptv.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

Data.Swagger.Operation

Contents

Description

Helper traversals and functions for Swagger operations manipulations. These might be useful when you already have Swagger specification generated by something else.

Synopsis

Operation traversals

allOperations :: Traversal' Swagger Operation Source #

All operations of a Swagger spec.

operationsOf :: Swagger -> Traversal' Swagger Operation Source #

operationsOf sub will traverse only those operations that are present in sub. Note that Operation is determined by both path and method.

>>> let ok = (mempty :: Operation) & at 200 ?~ "OK"
>>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ ok & post ?~ ok)]
>>> let sub = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
>>> encode api
"{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"description\":\"OK\"}}},\"post\":{\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}"
>>> encode $ api & operationsOf sub . at 404 ?~ "Not found"
"{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"404\":{\"description\":\"Not found\"},\"200\":{\"description\":\"OK\"}}},\"post\":{\"responses\":{\"200\":{\"description\":\"OK\"}}}}}}"

Manipulation

Tags

applyTags :: [Tag] -> Swagger -> Swagger Source #

Apply tags to all operations and update the global list of tags.

applyTags = applyTagsFor allOperations

applyTagsFor :: Traversal' Swagger Operation -> [Tag] -> Swagger -> Swagger Source #

Apply tags to a part of Swagger spec and update the global list of tags.

Responses

setResponse :: HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger Source #

Set response for all operations. This will also update global schema definitions.

If the response already exists it will be overwritten.

setResponse = setResponseFor allOperations

Example:

>>> let api = (mempty :: Swagger) & paths .~ [("/user", mempty & get ?~ mempty)]
>>> let res = declareResponse (Proxy :: Proxy Day)
>>> encode $ api & setResponse 200 res
"{\"swagger\":\"2.0\",\"info\":{\"version\":\"\",\"title\":\"\"},\"paths\":{\"/user\":{\"get\":{\"responses\":{\"200\":{\"schema\":{\"$ref\":\"#/definitions/Day\"},\"description\":\"\"}}}}},\"definitions\":{\"Day\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}}}"

See also setResponseWith.

setResponseWith :: (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger Source #

Set or update response for all operations. This will also update global schema definitions.

If the response already exists, but it can't be dereferenced (invalid $ref), then just the new response is used.

setResponseWith = setResponseForWith allOperations

See also setResponse.

setResponseFor :: Traversal' Swagger Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger Source #

Set response for specified operations. This will also update global schema definitions.

If the response already exists it will be overwritten.

See also setResponseForWith.

setResponseForWith :: Traversal' Swagger Operation -> (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger Source #

Set or update response for specified operations. This will also update global schema definitions.

If the response already exists, but it can't be dereferenced (invalid $ref), then just the new response is used.

See also setResponseFor.

Paths

prependPath :: FilePath -> Swagger -> Swagger Source #

Prepend path piece to all operations of the spec. Leading and trailing slashes are trimmed/added automatically.

>>> let api = (mempty :: Swagger) & paths .~ [("/info", mempty)]
>>> encode $ prependPath "user/{user_id}" api ^. paths
"{\"/user/{user_id}/info\":{}}"

Miscellaneous

declareResponse :: ToSchema a => Proxy a -> Declare (Definitions Schema) Response Source #

Construct a response with Schema while declaring all necessary schema definitions.

>>> encode $ runDeclare (declareResponse (Proxy :: Proxy Day)) mempty
"[{\"Day\":{\"example\":\"2016-07-22\",\"format\":\"date\",\"type\":\"string\"}},{\"description\":\"\",\"schema\":{\"$ref\":\"#/definitions/Day\"}}]"