Skip to main content

No project description provided

Project description

openapi-bridge

OpenAPI endpoint decorator with pydantic (>=2.0.0) integration.

Allows for almost seamless integration of pydantic models with OpenAPI, generating YAML for the endpoint from type hints.

Using the @endpoint decorator

Example:

@endpoint("/foo/{foo_id}")
def foo(*, foo_id: int, debug: Optional[bool] = False) -> pydantic_models.Foo:
   """
       Foo summary.

       Lengthy foo description.

       @param foo_id The Foo ID in the database.
       @param debug Set to True to include debug information.
   """
   result = _do_something(id, debug)
   return pydantic_models.Foo(**result)

As you can see from the example, the decorator takes a path (which may include a path parameter, in this case id). You can also give it an HTTP method, a path prefix (e.g. to distinguish between internal and external API functions), and security directives.

Information about the endpoint is gathered from both the type annotations of the decorated function and its docstring.

(!) Every parameter (except the optional user) must be keyword-only, have a type hint and a @param help text in the docstring. Un-annotated or undocumented parameters are considered to be a hard error and will raise an exception on startup.

Normally you can just return an instance of the annotated type, and the decorator will handle it correctly, adding an HTTP status 200. If you need to return something else, e.g. some redirect or a 204 ("no content"), you can to return a (raw_content, http_status) tuple instead, e.g.:

return None, 204

The docstring of an endpoint contains its summary, description, the section the documentation is listed under, and parameter help, as well as (optionally) its response in various circumstances.

The summary is the first paragraph of the docstring; the description is taken to be any further paragraphs until the first @keyword.

We recognize the following keywords to designate parts of the documentation:

  • @section <section name>: endpoint is listed in this section.
  • @param <param name> <help text>: explanation of the given parameter.
  • @example <param name> <example text>: example values of the parameter.
  • @response <http status> <JSON>: allows for non-standard responses.

YAML Generation

If you're building a Connexion app, you can use the collected endpoints in your create_app() function:

def create_app():
    # TODO: import all modules with @endpoints here!!
    api_specs = {
        "paths": openapi_bridge.PATHS["default"],
        **openapi_bridge.get_pydantic_schemata(pydantic_models),
    }
    connexion_app.add_api(api_specs)

(!) You need to import all the modules with endpoints here in order to register them. This is easy to forget! If you test a new endpoint and only ever get 404, you might have forgotten to import that module ;-)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

openapi-bridge-0.3.0.tar.gz (11.5 kB view details)

Uploaded Source

Built Distribution

openapi_bridge-0.3.0-py3-none-any.whl (12.2 kB view details)

Uploaded Python 3

File details

Details for the file openapi-bridge-0.3.0.tar.gz.

File metadata

  • Download URL: openapi-bridge-0.3.0.tar.gz
  • Upload date:
  • Size: 11.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.11 CPython/3.10.0 Darwin/23.4.0

File hashes

Hashes for openapi-bridge-0.3.0.tar.gz
Algorithm Hash digest
SHA256 d440e372a149cf62a601d867add9fec73bdcc1454ce3a3001f2d623bf6043a56
MD5 f2b1c57ce249322b8e1e48f7d00ca5dc
BLAKE2b-256 07b07e1b1663e54b057bd91b33eeddb36a818816a17a3e65b781d89db09e4e28

See more details on using hashes here.

File details

Details for the file openapi_bridge-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: openapi_bridge-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 12.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.11 CPython/3.10.0 Darwin/23.4.0

File hashes

Hashes for openapi_bridge-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 bb7b018137c5d606824af112064d0e0ce81aeda83ab2df094a58fa86c0c68688
MD5 6850c49dfad76f224c316de3ba016c70
BLAKE2b-256 392dcc37e322a125be9063f6dc1c618b72471ecb3a46ee775d15432eeb876ee2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page