Data.OpenApi.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' OpenApi Operation

All operations of a Swagger spec.

operationsOf :: OpenApi -> Traversal' OpenApi 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 :: OpenApi) & paths .~ [("/user", mempty & get ?~ ok & post ?~ ok)]
>>> let sub = (mempty :: OpenApi) & paths .~ [("/user", mempty & get ?~ mempty)]
>>> BSL.putStrLn $ encode api
{"openapi":"3.0.0","info":{"version":"","title":""},"paths":{"/user":{"get":{"responses":{"200":{"description":"OK"}}},"post":{"responses":{"200":{"description":"OK"}}}}},"components":{}}
>>> BSL.putStrLn $ encode $ api & operationsOf sub . at 404 ?~ "Not found"
{"openapi":"3.0.0","info":{"version":"","title":""},"paths":{"/user":{"get":{"responses":{"404":{"description":"Not found"},"200":{"description":"OK"}}},"post":{"responses":{"200":{"description":"OK"}}}}},"components":{}}

Manipulation

Tags

applyTags :: [Tag] -> OpenApi -> OpenApi

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

applyTags = applyTagsFor allOperations

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

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

Responses

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

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 :: OpenApi) & paths .~ [("/user", mempty & get ?~ mempty)]
>>> let res = declareResponse "application/json" (Proxy :: Proxy Day)
>>> BSL.putStrLn $ encode $ api & setResponse 200 res
{"openapi":"3.0.0","info":{"version":"","title":""},"paths":{"/user":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Day"}}},"description":""}}}}},"components":{"schemas":{"Day":{"example":"2016-07-22","format":"date","type":"string"}}}}

See also setResponseWith.

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

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' OpenApi Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> OpenApi -> OpenApi

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' OpenApi Operation -> (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> OpenApi -> OpenApi

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 -> OpenApi -> OpenApi

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

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

Miscellaneous

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

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

FIXME doc

>>> BSL.putStrLn $ encode $ runDeclare (declareResponse "application/json" (Proxy :: Proxy Day)) mempty
[{"Day":{"example":"2016-07-22","format":"date","type":"string"}},{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Day"}}}}]