specbook-fastapi 0.1.0__py3-none-any.whl

specbook_fastapi/__init__.py

@@ -0,0 +1,99 @@
+"""Serve the Specbook API viewer from a FastAPI app.
+
+from fastapi import FastAPI
+from specbook_fastapi import add_specbook
+
+app = FastAPI(docs_url=None, redoc_url=None)
+add_specbook(app, route="/docs")
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+
+from ._html import TESTED_VERSION, Cdn, render_embed, render_page, script_url
+
+try:
+    __version__ = _version("specbook-fastapi")
+except PackageNotFoundError:  # running from a source checkout that is not installed
+    __version__ = "0.0.0"
+
+__all__ = ["TESTED_VERSION", "add_specbook", "get_specbook_html", "__version__"]
+
+
+def get_specbook_html(
+    *,
+    openapi_url: str = "/openapi.json",
+    title: str = "API docs",
+    default_env: str | None = None,
+    base_url: str | None = None,
+    cdn: Cdn = "specbook",
+    version: str | None = None,
+    host: str | None = None,
+    src: str | None = None,
+    nonce: str | None = None,
+) -> HTMLResponse:
+    """A page that loads the Specbook viewer for the OpenAPI document at `openapi_url`.
+
+    Args:
+        openapi_url: The OpenAPI document. A relative address is resolved against the page.
+        title: The page title. It is HTML-escaped.
+        default_env: The environment shown first: `mock` (the viewer's default), `live`, or the name of a server in the
+            document.
+        base_url: Where live requests go when the document lists no server. Default: the page's own origin.
+        cdn: Where the viewer is loaded from: `specbook` (the stable `v1` channel at ui.specbook.dev) or `npm`
+            (`@specbook/ui` on jsDelivr).
+        version: With `specbook`, the channel (default `v1`). With `npm`, a version or range of `@specbook/ui`
+            (default: the release this package was tested with).
+        host: The host to load from instead of the one `cdn` names, for example `https://unpkg.com` or an internal
+            mirror.
+        src: The full address of `specbook.js`, for a copy you serve yourself. It overrides `cdn`, `version` and `host`.
+        nonce: A CSP nonce for the viewer's script.
+    """
+    embed = render_embed(
+        spec=openapi_url,
+        script=script_url(cdn=cdn, host=host, version=version, src=src),
+        base_url=base_url,
+        default_env=default_env,
+        nonce=nonce,
+    )
+    return HTMLResponse(render_page(title=title, embed=embed))
+
+
+def add_specbook(
+    app: FastAPI,
+    *,
+    route: str = "/specbook",
+    include_in_schema: bool = False,
+    **options: Any,
+) -> FastAPI:
+    """Serve the viewer at `route` for the app's own OpenAPI document.
+
+    The document's address and the page title come from the app (`app.openapi_url`, with the request's `root_path` in
+    front of it, so it works behind a prefix or a proxy, and `app.title`) unless you pass `openapi_url` or `title`. Any
+    other option is passed on to `get_specbook_html`. To replace FastAPI's own docs page, turn it off and take its
+    route::
+
+        app = FastAPI(docs_url=None, redoc_url=None)
+        add_specbook(app, route="/docs")
+    """
+    if "openapi_url" not in options and app.openapi_url is None:
+        raise ValueError(
+            "The app has no OpenAPI document (openapi_url is None). Pass openapi_url=... or enable the document."
+        )
+
+    @app.get(route, include_in_schema=include_in_schema, response_class=HTMLResponse)
+    async def specbook_docs(request: Request) -> HTMLResponse:
+        page = dict(options)
+        if "openapi_url" not in page:
+            root_path = request.scope.get("root_path", "").rstrip("/")
+            page["openapi_url"] = f"{root_path}{app.openapi_url}"
+        page.setdefault("title", app.title)
+        return get_specbook_html(**page)
+
+    return app

specbook_fastapi/_html.py

@@ -0,0 +1,92 @@
+"""The page that loads the Specbook viewer: pure functions, no FastAPI needed."""
+
+from __future__ import annotations
+
+import html
+import json
+from typing import Any, Literal
+
+Cdn = Literal["specbook", "npm"]
+
+#: The `@specbook/ui` release the `npm` host loads unless `version` is given.
+TESTED_VERSION = "0.6.0"
+
+SPECBOOK_HOST = "https://ui.specbook.dev"
+NPM_HOST = "https://cdn.jsdelivr.net/npm"
+DEFAULT_CHANNEL = "v1"
+
+
+def escape_html(value: str) -> str:
+    """Escape text for an HTML body or a quoted attribute."""
+    return html.escape(value, quote=True)
+
+
+def json_for_script(value: Any) -> str:
+    """JSON that is safe inside a `<script>` element: nothing in it can close the element or start a comment."""
+    return (
+        json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+        .replace("<", "\\u003c")
+        .replace(">", "\\u003e")
+        .replace("&", "\\u0026")
+        .replace("
", "\\u2028")
+        .replace("
", "\\u2029")
+    )
+
+
+def script_url(
+    *,
+    cdn: Cdn = "specbook",
+    host: str | None = None,
+    version: str | None = None,
+    src: str | None = None,
+) -> str:
+    """The address of `specbook.js`. `src` wins; otherwise `cdn` picks the host and `version` the release."""
+    if src is not None:
+        return src
+    if cdn == "npm":
+        base = (host or NPM_HOST).rstrip("/")
+        return f"{base}/@specbook/ui@{version or TESTED_VERSION}/dist-viewer/specbook.js"
+    if cdn == "specbook":
+        base = (host or SPECBOOK_HOST).rstrip("/")
+        return f"{base}/{version or DEFAULT_CHANNEL}/specbook.js"
+    raise ValueError(f"cdn must be 'specbook' or 'npm', not {cdn!r}")
+
+
+def render_embed(
+    *,
+    spec: str,
+    script: str,
+    base_url: str | None = None,
+    default_env: str | None = None,
+    nonce: str | None = None,
+) -> str:
+    """The three elements the viewer needs: its container, its configuration as data, and its module script."""
+    config: dict[str, str] = {"spec": spec}
+    if base_url is not None:
+        config["baseUrl"] = base_url
+    if default_env is not None:
+        config["defaultEnv"] = default_env
+    nonce_attr = "" if nonce is None else f' nonce="{escape_html(nonce)}"'
+    return "\n".join(
+        [
+            '<div id="app"></div>',
+            f'<script type="application/json" id="specbook-config">{json_for_script(config)}</script>',
+            f'<script type="module" src="{escape_html(script)}"{nonce_attr}></script>',
+        ]
+    )
+
+
+def render_page(*, title: str, embed: str) -> str:
+    """A whole page around the embed. The viewer takes over the page, so it gets one of its own."""
+    return f"""<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{escape_html(title)}</title>
+  </head>
+  <body>
+{embed}
+  </body>
+</html>
+"""

specbook_fastapi-0.1.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.5
+Name: specbook-fastapi
+Version: 0.1.0
+Summary: Serve the Specbook API viewer from a FastAPI app
+Project-URL: Homepage, https://docs.specbook.dev
+Project-URL: Viewer, https://ui.specbook.dev
+Project-URL: Source, https://github.com/specbook-dev/specbook/tree/main/integrations/fastapi
+Project-URL: Issues, https://github.com/specbook-dev/specbook/issues
+Author: Ajai Shankar
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-docs,api-documentation,fastapi,openapi,specbook,swagger
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100
+Description-Content-Type: text/markdown
+
+# specbook-fastapi
+
+Serves the [Specbook UI](https://ui.specbook.dev) for your FastAPI app's OpenAPI document. It reads the document in the browser and lets a visitor send each request: against **mock** responses built from the document's examples, or **live** against your API. It runs on your app's own origin, so there is no CORS to configure and the visitor's cookies are sent.
+
+<img src="https://raw.githubusercontent.com/specbook-dev/specbook/main/.github/screenshot-pair.png" alt="Specbook with the Petstore spec open on a laptop and on a phone" width="840" />
+
+See the [Specbook docs](https://docs.specbook.dev) for what else it can do: requests with checks, flows, tests that run in CI, and a portal for QA.
+
+The package only returns an HTML page that loads the viewer, so it adds nothing to your app but one route.
+
+## Installation
+
+```bash
+pip install specbook-fastapi
+# or
+uv add specbook-fastapi
+```
+
+Python 3.10 or newer, and FastAPI.
+
+## Usage
+
+Serve the viewer at `/specbook` for the app's own OpenAPI document:
+
+```python
+from fastapi import FastAPI
+from specbook_fastapi import add_specbook
+
+app = FastAPI()
+add_specbook(app)  # the viewer is at /specbook
+```
+
+To use it instead of FastAPI's own docs page, turn that off and take its route:
+
+```python
+app = FastAPI(docs_url=None, redoc_url=None)
+add_specbook(app, route="/docs")
+```
+
+The document's address and the page title come from the app (`app.openapi_url`, with the request's `root_path` in front of it, so it works behind a prefix or a proxy, and `app.title`). The route is left out of the OpenAPI document.
+
+### Your own route
+
+`get_specbook_html` returns an `HTMLResponse`, for when you want to set the route up yourself:
+
+```python
+from fastapi import FastAPI
+from specbook_fastapi import get_specbook_html
+
+app = FastAPI(docs_url=None)
+
+
+@app.get("/docs", include_in_schema=False)
+async def docs():
+    return get_specbook_html(openapi_url=app.openapi_url, title=f"{app.title} docs", default_env="live")
+```
+
+## Options
+
+`add_specbook` takes `route` and `include_in_schema`, and passes every other keyword argument on to `get_specbook_html`.
+
+| Option        | Type                    | Default                | Description                                                                                                                      |
+| ------------- | ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `openapi_url` | `str`                   | `/openapi.json`        | The OpenAPI document. A relative address is resolved against the page. `add_specbook` takes it from the app.                     |
+| `title`       | `str`                   | `API docs`             | The page title. It is HTML-escaped. `add_specbook` takes it from the app.                                                        |
+| `default_env` | `str`                   | `mock`                 | The environment shown first: `mock`, `live`, or the name of a server in the document.                                            |
+| `base_url`    | `str`                   | the page's own origin  | Where live requests go when the document lists no server.                                                                        |
+| `cdn`         | `"specbook"` \| `"npm"` | `"specbook"`           | Where the viewer is loaded from: the stable `v1` channel at `ui.specbook.dev`, or `@specbook/ui` on jsDelivr.                    |
+| `version`     | `str`                   | `v1` / tested release  | With `specbook`, the channel. With `npm`, a version or range of `@specbook/ui`. The default is the release this was tested with. |
+| `host`        | `str`                   | the host of `cdn`      | The host, for example `https://unpkg.com` or an internal mirror.                                                                 |
+| `src`         | `str`                   |                        | The full address of `specbook.js`, for a copy you serve yourself. It overrides `cdn`, `version` and `host`.                      |
+| `nonce`       | `str`                   |                        | A [CSP nonce](https://developer.mozilla.org/docs/Web/HTTP/CSP#nonces) for the viewer's script.                                   |
+
+The viewer's own settings (`default_env`, the page title, the Content-Security-Policy it needs) are described in the [embed reference](https://docs.specbook.dev/reference/embed/).
+
+The `specbook` host is the newest deployed build of the `v1` line, so fixes reach your app without a new release of this package. A breaking change to the viewer would ship as `/v2/`. The `npm` host is an immutable release of `@specbook/ui`; pin `version` to hold it still.
+
+## Content-Security-Policy
+
+The page has no inline script. The JSON that configures the viewer is data, so it needs no nonce, and the one module script takes `nonce` when your policy uses nonces.
+
+| Where the viewer comes from | The policy needs                                                                      |
+| --------------------------- | ------------------------------------------------------------------------------------- |
+| A copy you serve (`src`)    | `script-src 'self'` and `worker-src 'self'`                                           |
+| `ui.specbook.dev`           | that host in `script-src`, `style-src` and `worker-src`, plus `blob:` in `worker-src` |
+| jsDelivr (`cdn="npm"`)      | `https://cdn.jsdelivr.net` in the same three directives, plus `blob:` in `worker-src` |
+
+## Privacy
+
+The viewer runs no analytics or tracking script, and your document and your API's responses stay in the visitor's browser; nothing is sent to Specbook. Loading the script from `ui.specbook.dev` or jsDelivr means that host sees the visitor's IP address and the file requests, as any CDN does; [serve the viewer yourself](#serving-the-viewer-yourself) to avoid that.
+
+The overview shows a small "Powered by Specbook" link. It points to `docs.specbook.dev` with your site's hostname in the address, and the Specbook docs site uses Cloudflare Web Analytics.
+
+## Serving the viewer yourself
+
+Every Specbook release carries the viewer's files as `specbook-viewer-<version>.zip` (MIT, with its third-party licence notices) on its [GitHub release](https://github.com/specbook-dev/specbook/releases), and `@specbook/ui` on npm ships the same files in `dist-viewer/`. Unpack them into a folder, serve it from your app and point `src` at it, so nothing is loaded from another host:
+
+```python
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from specbook_fastapi import add_specbook
+
+app = FastAPI(docs_url=None, redoc_url=None)
+app.mount("/specbook-viewer", StaticFiles(directory="specbook-viewer"), name="specbook-viewer")
+add_specbook(app, route="/docs", src="/specbook-viewer/specbook.js")
+```
+
+## Author
+
+Maintained by the [Specbook](https://github.com/specbook-dev/specbook) team. Issues are welcome at [specbook-dev/specbook](https://github.com/specbook-dev/specbook/issues).
+
+## License
+
+MIT

specbook_fastapi-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+specbook_fastapi/__init__.py,sha256=GGCa3BG4qg-J2rfuEDSArdw_VszQJPRubh_Uk4A6rH8,3879
+specbook_fastapi/_html.py,sha256=dn-5ncMOfx2G2PRfT-P6Yprti5MJQuqxGU0TRq4zXXM,2868
+specbook_fastapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+specbook_fastapi-0.1.0.dist-info/METADATA,sha256=3m3vQPHVHAYxfNwnfvySYfBow-nJs8TkUwmio1citXU,8072
+specbook_fastapi-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+specbook_fastapi-0.1.0.dist-info/licenses/LICENSE,sha256=mAuNVlLgsfI3K4qHktqIH-5z6nEPT1k02xpMjCNf7KI,1069
+specbook_fastapi-0.1.0.dist-info/RECORD,,

specbook_fastapi-0.1.0.dist-info/WHEEL

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

specbook_fastapi-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajai Shankar
+
+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.