API

require

class fastapi_icontract.require

Decorate a FastAPI endpoint with a pre-condition.

__init__(condition: CallableT, status_code: int = 422, description: Optional[str] = None, enforced: bool = True, undocument: bool = False) → None

Initialize.

Parameters

• condition –

  pre-condition predicate.

  The arguments of the pre-condition are expected to be a subset of the endpoint arguments.

  It can either be a sync function, a lambda, an async function. If the condition returns a coroutine, the coroutine will be awaited first, and then checked for truthiness.

• status_code – If the pre-condition is violated, the checker will raise a fastapi.HTTPException. This status_code will be indicated in the exception.

• description –

  textual description of the pre-condition.

  The description will be included in the exception if the pre-condition is violated.

• enforced –

  If set, the pre-condition is enforced.

  Otherwise, the pre-condition is only added to the OpenAPI schema, but is not verified. Usually, you enforce certain slow pre-conditions during testing and then disable them in production. An unenforced pre-condition is however still useful for the client as a formal documentation which is at least verified during testing.

• undocument – If set, the pre-condition is not documented in the OpenAPI schema.

__call__(func: CallableT) → CallableT

Add the pre-condition to the checker of a FastAPI endpoint.

Parameters

func – endpoint function to be wrapped

Returns

wrapped endpoint

snapshot

class fastapi_icontract.snapshot

Add a snapshot to the checker of an FastAPI endpoint.

This will decorate the endpoint with a snapshot of argument values captured prior to the invocation.

A snapshot is defined by a capture function (usually a lambda) that accepts one or more arguments of the function.

The captured values are supplied to post-conditions with the OLD argument of the condition.

__init__(capture: CallableT, name: str, enabled: bool = True, undocument: bool = False) → None

Initialize.

Parameters

• capture –

  function to capture the snapshot accepting a one or more arguments of the original function prior to the execution.

  The capture can either be a lambda, a sync function or an async function. If capture returns a coroutine, the coroutine will be first awaited before it is stored into the OLD structure.

• name – name of the snapshot as will be stored in the OLD structure.

• enabled –

  The snapshot is applied only if enabled is set. Otherwise, the snapshot is disabled and there is no run-time overhead.

  Usually the snapshots are enabled and disabled together with their related post-conditions.

• undocument – If set, the snapshot is not documented in the OpenAPI schema.

__call__(func: CallableT) → CallableT

Add the snapshot to the checker of a FastAPI endpoint func.

The function func is expected to be decorated with at least one postcondition before the snapshot.

Parameters

func – function whose arguments we need to snapshot

Returns

func as given in the input

ensure

class fastapi_icontract.ensure

Decorate a FastAPI endpoint with a post-condition.

__init__(condition: CallableT, status_code: int = 500, description: Optional[str] = None, enforced: bool = True, undocument: bool = False) → None

Initialize.

Parameters

• condition –

  post-condition predicate.

  The arguments of the post-condition are expected to be a subset of the endpoint arguments.

  It can either be a sync function, a lambda, an async function. If the condition returns a coroutine, the coroutine will be awaited first, and then checked for truthiness.

• status_code – If the post-condition is violated, the checker will raise a fastapi.HTTPException. This status_code will be indicated in the exception.

• description –

  textual description of the post-condition.

  The description will be included in the exception if the post-condition is violated.

• enforced –

  If set, the post-condition is enforced.

  Otherwise, the post-condition is only added to the OpenAPI schema, but is not verified. Usually, you enforce post-conditions during testing and then disable them all in production. An unenforced post-condition is however still useful for the client as a formal documentation which is at least verified during testing.

• undocument – If set, the post-condition is not documented in the OpenAPI schema.

__call__(func: CallableT) → CallableT

Add the postcondition to the checker of a FastAPI endpoint.

If the endpoint has not been already wrapped with a checker, this will wrap it with a checker first.

Parameters

func – endpoint function to be wrapped

Returns

wrapped endpoint

wrap_openapi_with_contracts

fastapi_icontract.wrap_openapi_with_contracts(app: fastapi.applications.FastAPI) → None

Wrap the openapi method of the app to include the contracts in the schema.

set_up_route_for_docs_with_contracts_plugin

fastapi_icontract.set_up_route_for_docs_with_contracts_plugin(app: fastapi.applications.FastAPI, path: str = '/docs') → None

Set up the route for Swagger UI with included plugin swagger-ui-plugin-contracts.

The path must not be set before. You must explicitly tell FastAPI to exclude it during initialization with:

app = FastAPI(docs_url=None)

get_swagger_ui_html

fastapi_icontract.swagger_ui.get_swagger_ui_html(*, openapi_url: str, title: str, swagger_js_url: str = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui-bundle.js', swagger_css_url: str = 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css', swagger_favicon_url: str = 'https://fastapi.tiangolo.com/img/favicon.png', swagger_ui_plugin_contracts_url: str = 'https://unpkg.com/swagger-ui-plugin-contracts', oauth2_redirect_url: Optional[str] = None, init_oauth: Optional[Dict[str, Any]] = None) → starlette.responses.HTMLResponse

Generate the HTML for Swagger UI endpoint.

This is a patched version of the original fastapi.applications.get_swagger_ui_html which includes a separate JavaScript code to display contracts in a pretty format.