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

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

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 .~ IOHM.fromList [("/info", mempty)]
>>> BSL.putStrLn $ encodePretty $ 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 $ encodePretty $ runDeclare (declareResponse "application/json" (Proxy :: Proxy Day)) mempty
[
    {
        "Day": {
            "example": "2016-07-22",
            "format": "date",
            "type": "string"
        }
    },
    {
        "content": {
            "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/Day"
                }
            }
        },
        "description": ""
    }
]