Metadata-Version: 2.1
Name: openapi-bridge
Version: 0.5.0
Summary: 
Home-page: https://github.com/solute/openapi-bridge
License: Apache-2.0
Author: Patrick Schemitz
Author-email: ps@solute.de
Requires-Python: >=3.9,<4.0
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: pydantic (>=2.1.1,<3.0.0)
Project-URL: Repository, https://github.com/solute/openapi-bridge
Description-Content-Type: text/markdown

# 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:

```python
@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.:

```python
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:

```python
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 ;-)

