azure-functions-openapi 0.4.0__py3-none-any.whl

azure_functions_openapi/__init__.py

@@ -0,0 +1,3 @@
+# src/azure_functions_openapi/__init__.py
+
+__version__ = "0.4.0"

azure_functions_openapi/decorator.py

@@ -0,0 +1,143 @@
+# src/azure_functions_openapi/decorator.py
+from typing import Any, Callable, Dict, List, Optional, Type, TypeVar
+
+from pydantic import BaseModel
+
+# Define a generic type variable for functions
+F = TypeVar("F", bound=Callable[..., Any])
+
+# Global registry to hold OpenAPI metadata for each function
+_openapi_registry: Dict[str, Dict[str, Any]] = {}
+
+
+def openapi(
+    # ── basic metadata ───────────────────────────────────────────
+    summary: str = "",
+    description: str = "",
+    tags: Optional[List[str]] = None,
+    operation_id: Optional[str] = None,
+    # ── routing information ─────────────────────────────────────
+    route: Optional[str] = None,
+    method: Optional[str] = None,
+    parameters: Optional[List[Dict[str, Any]]] = None,
+    # ── request / response schema ───────────────────────────────
+    request_model: Optional[Type[BaseModel]] = None,
+    request_body: Optional[Dict[str, Any]] = None,
+    response_model: Optional[Type[BaseModel]] = None,
+    response: Optional[Dict[int, Dict[str, Any]]] = None,
+) -> Callable[[F], F]:
+    """
+    Decorator that attaches OpenAPI metadata to an Azure Functions handler.
+
+    Examples
+    --------
+    ### 1 · Minimal “Hello World”
+
+    ```python
+    @app.route(route="hello")
+    @openapi(summary="Hello", description="Returns plain text.")
+    def hello(req: func.HttpRequest) -> func.HttpResponse:
+        return func.HttpResponse("Hello, world!", status_code=200)
+    ```
+
+    ### 2 · Pydantic-powered JSON API
+
+    ```python
+    from pydantic import BaseModel
+
+    class TodoRequest(BaseModel):
+        title: str
+        done: bool = False
+
+    class TodoResponse(BaseModel):
+        id: int
+        title: str
+        done: bool
+
+    @app.route(route="todos/{id}", method="put")
+    @openapi(
+        summary="Update a todo item",
+        description=\"""Update a todo and return the updated document.\""",
+        tags=["Todo"],
+        parameters=[{"name": "id", "in": "path", "required": True, "schema": {"type": "integer"}}],
+        request_model=TodoRequest,
+        response_model=TodoResponse,
+        operation_id="updateTodo",
+    )
+    def update_todo(req: func.HttpRequest) -> func.HttpResponse:
+        # ... business logic ...
+        body = TodoRequest.model_validate_json(req.get_body())
+        todo = TodoResponse(id=1, **body.model_dump())
+        return func.HttpResponse(
+            todo.model_dump_json(),
+            status_code=200,
+            mimetype="application/json",
+        )
+    ```
+
+    After starting the Function App you get:
+
+    * **Swagger UI** → `http://localhost:7071/api/docs`
+    * **Raw JSON spec** → `http://localhost:7071/api/openapi.json`
+
+    Parameters
+    ----------
+    summary:
+        Short description shown in Swagger UI.
+    description:
+        Longer Markdown-enabled description.
+    tags:
+        List of group tags.
+    operation_id:
+        Custom operationId (defaults to function name).
+    route:
+        Override for the HTTP route path (e.g. "/items/{id}").
+    method:
+        Explicit HTTP method if not inferrable.
+    parameters:
+        List of param objects (query/path/header/cookie).
+    request_model:
+        Pydantic model used to derive requestBody schema.
+    request_body:
+        Raw requestBody schema (if you don’t use Pydantic).
+    response_model:
+        Pydantic model used to derive 200-response schema.
+    response:
+        Manual responses dict keyed by status code.
+
+    Returns
+    -------
+    Callable
+        The original function, with its name stored in `_openapi_registry`.
+    """
+
+    def decorator(func: F) -> F:
+        _openapi_registry[func.__name__] = {
+            # ── basic metadata ────────────────────────────────
+            "summary": summary,
+            "description": description,
+            "tags": tags or ["default"],
+            "operation_id": operation_id,
+            # ── routing info ─────────────────────────────────
+            "route": route,
+            "method": method,
+            "parameters": parameters or [],
+            # ── request / response schema ────────────────────
+            "request_model": request_model,
+            "request_body": request_body,
+            "response_model": response_model,
+            "response": response or {},
+        }
+        return func
+
+    return decorator
+
+
+def get_openapi_registry() -> Dict[str, Dict[str, Any]]:
+    """
+    Retrieve OpenAPI metadata for all registered functions.
+
+    Returns:
+        A dictionary where each key is a function name and value is its OpenAPI metadata.
+    """
+    return _openapi_registry

azure_functions_openapi/openapi.py

@@ -0,0 +1,99 @@
+# src/azure_functions_openapi/openapi.py
+import json
+from typing import Any, Dict, List
+
+import yaml
+
+from azure_functions_openapi.decorator import get_openapi_registry
+from azure_functions_openapi.utils import model_to_schema
+
+
+def generate_openapi_spec(title: str = "API", version: str = "1.0.0") -> Dict[str, Any]:
+    """
+    Compile an OpenAPI-3 specification from the registry.
+    No base-path is added; `route=` is used exactly as provided.
+    """
+    registry = get_openapi_registry()
+    paths: Dict[str, Dict[str, Any]] = {}
+
+    for func_name, meta in registry.items():
+        # route & method --------------------------------------------------
+        path = meta.get("route") or f"/{func_name}"
+        method = (meta.get("method") or "get").lower()
+
+        # responses -------------------------------------------------------
+        responses: Dict[str, Any] = {}
+        for status, detail in meta.get("response", {}).items():
+            resp = {"description": detail.get("description", "")}
+            if "content" in detail:
+                resp["content"] = detail["content"]
+            responses[str(status)] = resp
+
+        if meta.get("response_model"):
+            responses["200"] = {
+                "description": "Successful Response",
+                "content": {
+                    "application/json": {"schema": model_to_schema(meta["response_model"])}
+                },
+            }
+
+        # operation object ------------------------------------------------
+        op: Dict[str, Any] = {
+            "summary": meta.get("summary", ""),
+            "description": meta.get("description", ""),
+            "operationId": meta.get("operation_id") or f"{method}_{func_name}",
+            "tags": meta.get("tags") or ["default"],
+            "responses": responses,
+        }
+
+        # parameters ------------------------------------------------------
+        parameters: List[Dict[str, Any]] = meta.get("parameters", [])
+        if parameters:
+            op["parameters"] = parameters
+
+        # requestBody (POST/PUT/PATCH) ------------------------------------
+        if method in {"post", "put", "patch"}:
+            if meta.get("request_body"):
+                op["requestBody"] = {
+                    "required": True,
+                    "content": {"application/json": {"schema": meta["request_body"]}},
+                }
+            elif meta.get("request_model"):
+                op["requestBody"] = {
+                    "required": True,
+                    "content": {
+                        "application/json": {"schema": model_to_schema(meta["request_model"])}
+                    },
+                }
+
+        # merge into paths (support multiple methods per route) ----------
+        paths.setdefault(path, {})[method] = op
+
+    return {
+        "openapi": "3.0.0",
+        "info": {
+            "title": title,
+            "version": version,
+            "description": (
+                "Auto-generated OpenAPI documentation. "
+                "Markdown supported in descriptions (CommonMark)."
+            ),
+        },
+        "paths": paths,
+    }
+
+
+def get_openapi_json() -> str:
+    """Return the spec as pretty-printed JSON (UTF-8).
+    Returns:
+        str: OpenAPI spec in JSON format.
+    """
+    return json.dumps(generate_openapi_spec(), indent=2, ensure_ascii=False)
+
+
+def get_openapi_yaml() -> str:
+    """Return the spec as YAML.
+    Returns:
+        str: OpenAPI spec in YAML format.
+    """
+    return yaml.safe_dump(generate_openapi_spec(), sort_keys=False, allow_unicode=True)

azure_functions_openapi/swagger_ui.py

@@ -0,0 +1,28 @@
+from azure.functions import HttpResponse
+
+
+def render_swagger_ui() -> HttpResponse:
+    html_content = """
+    <!DOCTYPE html>
+    <html>
+      <head>
+        <title>Swagger UI</title>
+        <link rel="stylesheet" 
+              type="text/css" 
+              href="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui.css" />
+      </head>
+      <body>
+        <div id="swagger-ui"></div>
+        <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist/swagger-ui-bundle.js"></script>
+        <script>
+          const ui = SwaggerUIBundle({
+            url: '/api/openapi.json',
+            dom_id: '#swagger-ui',
+            presets: [SwaggerUIBundle.presets.apis],
+            layout: 'BaseLayout'
+          });
+        </script>
+      </body>
+    </html>
+    """
+    return HttpResponse(html_content, mimetype="text/html")

azure_functions_openapi/utils.py

@@ -0,0 +1,20 @@
+# src/azure_functions_openapi/utils.py
+from typing import Any, Dict, cast
+
+from packaging import version
+import pydantic
+
+PYDANTIC_V2 = version.parse(pydantic.__version__) >= version.parse("2.0.0")
+
+
+def model_to_schema(model_cls: Any) -> Dict[str, Any]:
+    """Return JSON schema from a Pydantic model class.
+    Parameters:
+        model_cls: Pydantic model class.
+    Returns:
+        Dict[str, Any]: JSON schema representation of the model.
+    """
+
+    if PYDANTIC_V2:
+        return cast(Dict[str, Any], model_cls.model_json_schema())
+    return cast(Dict[str, Any], model_cls.schema())

azure_functions_openapi-0.4.0.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: azure-functions-openapi
+Version: 0.4.0
+Summary: OpenAPI (Swagger) integration for Python-based Azure Functions
+Author-email: Yeongseon Choe <yeongseon.choe@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: <3.13,>=3.9
+Requires-Dist: azure-functions
+Requires-Dist: pydantic<3.0,>=1.10
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: bandit; extra == 'dev'
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: git-changelog; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# azure-functions-openapi
+
+[![PyPI](https://img.shields.io/pypi/v/azure-functions-openapi.svg)](https://pypi.org/project/azure-functions-openapi/)
+[![Python Version](https://img.shields.io/pypi/pyversions/azure-functions-openapi.svg)](https://pypi.org/project/azure-functions-openapi/)
+[![CI](https://github.com/yeongseon/azure-functions-openapi/actions/workflows/test.yml/badge.svg)](https://github.com/yeongseon/azure-functions-openapi/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/yeongseon/azure-functions-openapi/branch/main/graph/badge.svg)](https://codecov.io/gh/yeongseon/azure-functions-openapi)
+[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://pre-commit.com/)
+[![Docs](https://img.shields.io/badge/docs-gh--pages-blue)](https://yeongseon.github.io/azure-functions-openapi/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> Effortless OpenAPI (Swagger) documentation & Swagger‑UI for **Python Azure Functions**.
+
+---
+
+## Features
+
+- `@openapi` decorator — annotate once, generate full spec
+- Serves `/openapi.json`, `/openapi.yaml`, and `/docs` (Swagger UI)
+- Supports query/path/header parameters, requestBody, responses, tags
+- Optional Pydantic integration (supports both v1 and v2)
+- Zero hard dependency on Pydantic
+
+---
+
+## Installation
+
+```bash
+pip install azure-functions-openapi
+```
+
+For local development:
+
+```bash
+git clone https://github.com/yeongseon/azure-functions-openapi.git
+cd azure-functions-openapi
+pip install -e .[dev]
+```
+
+---
+
+## Quick Start
+
+> Create a minimal HTTP-triggered Azure Function with auto Swagger documentation.
+
+1. Set up environment
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install azure-functions azure-functions-worker azure-functions-openapi
+```
+
+2. Initialize Azure Functions project
+```bash
+func init hello_openapi --python
+cd hello_openapi
+```
+
+3. Add `function_app.py` with OpenAPI-decorated function and endpoints:
+```python
+# hello_openapi/function_app.py
+
+import json
+import azure.functions as func
+from azure_functions_openapi.decorator import openapi
+from azure_functions_openapi.openapi import get_openapi_json, get_openapi_yaml
+from azure_functions_openapi.swagger_ui import render_swagger_ui
+
+app = func.FunctionApp()
+
+@openapi(
+    summary="Greet user",
+    route="/api/http_trigger",
+    request_model={"name": "string"},
+    response_model={"message": "string"},
+    tags=["Example"]
+)
+@app.function_name(name="http_trigger")
+@app.route(route="/api/http_trigger", auth_level=func.AuthLevel.ANONYMOUS, methods=["POST"])
+def main(req: func.HttpRequest) -> func.HttpResponse:
+    try:
+        data = req.get_json()
+        name = data.get("name", "world")
+        return func.HttpResponse(
+            json.dumps({"message": f"Hello, {name}!"}),
+            mimetype="application/json"
+        )
+    except Exception as e:
+        return func.HttpResponse(f"Error: {str(e)}", status_code=400)
+
+@app.function_name(name="openapi_json")
+@app.route(route="/api/openapi.json", auth_level=func.AuthLevel.ANONYMOUS, methods=["GET"])
+def openapi_json(req: func.HttpRequest) -> func.HttpResponse:
+    return get_openapi_json()
+
+@app.function_name(name="openapi_yaml")
+@app.route(route="/api/openapi.yaml", auth_level=func.AuthLevel.ANONYMOUS, methods=["GET"])
+def openapi_yaml(req: func.HttpRequest) -> func.HttpResponse:
+    return get_openapi_yaml()
+
+@app.function_name(name="swagger_ui")
+@app.route(route="/api/docs", auth_level=func.AuthLevel.ANONYMOUS, methods=["GET"])
+def swagger_ui(req: func.HttpRequest) -> func.HttpResponse:
+    return render_swagger_ui()
+```
+>  Swagger UI (`/docs`) is now supported via `render_swagger_ui()` helper.
+
+4. Run locally:
+```bash
+func start
+```
+
+- OpenAPI JSON: http://localhost:7071/api/openapi.json
+- Swagger UI: http://localhost:7071/api/docs
+
+5. Deploy:
+```bash
+func azure functionapp publish <FUNCTION-APP-NAME> --python
+```
+
+- OpenAPI JSON: https://<FUNCTION-APP-NAME>.azurewebsites.net/api/openapi.json
+
+A partial example of the generated `/api/openapi.json`:
+
+```json
+{
+  "openapi": "3.0.0",
+  "info": {
+    "title": "API",
+    "version": "1.0.0",
+    "description": "Auto-generated OpenAPI documentation. Markdown supported in descriptions (CommonMark)."
+  },
+  "paths": {
+    "/api/http_trigger": {
+      "get": {
+        "summary": "HTTP Trigger with name parameter",
+        "description": "Returns a greeting using the **name** from query or body.",
+        "parameters": [
+          {
+            "name": "name",
+            "in": "query",
+            "required": true,
+            "schema": { "type": "string" },
+            "description": "Name to greet"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful response with greeting",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "sample": {
+                    "summary": "Example greeting",
+                    "value": {
+                      "message": "Hello, Azure!"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": { "description": "Invalid request" }
+        }
+      }
+    }
+  }
+}
+```
+
+- Swagger UI: https://<FUNCTION-APP-NAME>.azurewebsites.net/api/docs
+
+Swagger UI will look once you set up the routes:
+
+![Swagger UI Example](./docs/assets/hello_openapi_swagger_ui_preview.png)
+
+---
+
+## Example with Pydantic
+
+```python
+from pydantic import BaseModel
+from azure_functions_openapi.decorator import openapi
+
+class RequestModel(BaseModel):
+    name: str
+
+class ResponseModel(BaseModel):
+    message: str
+
+@openapi(
+    summary="Greet user (Pydantic)",
+    route="/api/http_trigger",
+    request_model=RequestModel,
+    response_model=ResponseModel,
+    tags=["Example"]
+)
+def http_trigger(req: func.HttpRequest) -> func.HttpResponse:
+    ...
+```
+
+>  Supports both Pydantic v1 and v2.
+Schema inference will work automatically with either version.
+
+---
+
+## Documentation
+
+- Full docs: [yeongseon.github.io/azure-functions-openapi](https://yeongseon.github.io/azure-functions-openapi/)
+- [Quickstart](docs/usage.md)
+- [Development Guide](docs/development.md)
+- [Contribution Guide](docs/contributing.md)
+
+---
+
+## License
+
+MIT © 2025 Yeongseon Choe

azure_functions_openapi-0.4.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+azure_functions_openapi/__init__.py,sha256=3espqW3_xVQoBqi0ha08IP22z55rFwElswG-a0ao18c,65
+azure_functions_openapi/decorator.py,sha256=7rDj-MD-PKSvZHSjCFF-OIRo2sLygyNeF2hA2T58O0g,5009
+azure_functions_openapi/openapi.py,sha256=0X35QpYDRxT2FblaMiQyhKHRCrpmK4bgQNcIvXBOCxA,3558
+azure_functions_openapi/swagger_ui.py,sha256=AGB4oAlQA3ayMREk5UskNwfahifOcPh_jzfTyK5z3ok,834
+azure_functions_openapi/utils.py,sha256=xzZn7-DfC_OktsuS3WTFiDruTBeNGOwxnKhYvIBsqps,593
+azure_functions_openapi-0.4.0.dist-info/METADATA,sha256=G5ZCaw72tMl1VTfj_mDhgNuludQX4nQXI6sECP0iGSg,7245
+azure_functions_openapi-0.4.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+azure_functions_openapi-0.4.0.dist-info/licenses/LICENSE,sha256=gBTzk1NFKuyZKqa5-8leVY816k7POZUMpw2_PKl2MsY,1071
+azure_functions_openapi-0.4.0.dist-info/RECORD,,

azure_functions_openapi-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

azure_functions_openapi-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yeongseon Choe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.