swagger2-2.1.4.1: Swagger 2.0 data model

Maintainer | Nickolay Kudasov <nickolay@getshoptv.com>
Stability | experimental
Safe Haskell | None
Language | Haskell2010

Data.Swagger.Operation

Contents

- Operation traversals
- Manipulation
  - Tags
  - Responses
  - Paths
- Miscellaneous

Description

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

Synopsis

- allOperations :: Traversal' Swagger Operation
- operationsOf :: Swagger -> Traversal' Swagger Operation
- applyTags :: [Tag] -> Swagger -> Swagger
- applyTagsFor :: Traversal' Swagger Operation -> [Tag] -> Swagger -> Swagger
- setResponse :: HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
- setResponseWith :: (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
- setResponseFor :: Traversal' Swagger Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
- setResponseForWith :: Traversal' Swagger Operation -> (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> Swagger -> Swagger
- prependPath :: FilePath -> Swagger -> Swagger
- declareResponse :: ToSchema a => proxy a -> Declare (Definitions Schema) Response

# 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 .~ [("/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 #

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.

## 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 .~ [("/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 #

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 .~ [("/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\"}}]"