Data.Swagger.Operation

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

Operation traversals

allOperations :: Traversal' Swagger Operation

All operations of a Swagger spec.

operationsOf :: Swagger -> Traversal' Swagger Operation

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

Manipulation

Tags

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

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

applyTags = applyTagsFor allOperations

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

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

Extensions

addExtensions :: (Value -> Value -> Value) -> InsOrdHashMap Text Value -> Swagger -> Swagger

addExtensionsFor :: Traversal' Swagger Operation -> (Value -> Value -> Value) -> InsOrdHashMap Text Value -> Swagger -> Swagger

Responses

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

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

See also setResponseWith.

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

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

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

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

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

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

Miscellaneous

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

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\"}}]"