openapi3-3.1.0: OpenAPI 3.0 data model
MaintainerNickolay Kudasov <nickolay@getshoptv.com>
Stabilityexperimental
Safe HaskellNone
LanguageHaskell2010

Data.OpenApi.Operation

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' OpenApi Operation Source #

All operations of a Swagger spec.

operationsOf :: OpenApi -> Traversal' OpenApi 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 :: OpenApi) & paths .~ [("/user", mempty & get ?~ ok & post ?~ ok)]
>>> let sub = (mempty :: OpenApi) & paths .~ [("/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 Source #

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

applyTags = applyTagsFor allOperations

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

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

Responses

setResponse :: HttpStatusCode -> Declare (Definitions Schema) Response -> OpenApi -> OpenApi 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 :: OpenApi) & paths .~ [("/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 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' OpenApi Operation -> HttpStatusCode -> Declare (Definitions Schema) Response -> OpenApi -> OpenApi 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' OpenApi Operation -> (Response -> Response -> Response) -> HttpStatusCode -> Declare (Definitions Schema) Response -> OpenApi -> OpenApi 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 -> OpenApi -> OpenApi Source #

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 $ encodePretty $ prependPath "user/{user_id}" api ^. paths
{
    "/user/{user_id}/info": {}
}

Miscellaneous

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

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