feat: Add opt-in route_json param to serve the spec as JSON

The spec dict is already parsed at registration time, so serving it
as JSON is just another view on the same data. Off by default.

Resolves #10

Author: miketheman

README.md

@@ -67,6 +67,8 @@ The reason this package exists is to give you peace of mind when providing a RES
     config.pyramid_openapi3_add_explorer(route='/api/v1/')
     ```
 
+    Pass `route_json='/api/v1/openapi.json'` to `pyramid_openapi3_spec` to also serve the spec as JSON (off by default).
+
 3. Use the `openapi` [view predicate](https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/viewconfig.html#view-configuration-parameters) to enable request/response validation:
 
     ```python

pyramid_openapi3/__init__.py

@@ -257,6 +257,7 @@ def add_spec_view(
     filepath: str,
     route: str = "/openapi.yaml",
     route_name: str = "pyramid_openapi3.spec",
+    route_json: str | None = None,
     permission: str = NO_PERMISSION_REQUIRED,
     apiname: str = "pyramid_openapi3",
 ) -> None:
@@ -265,6 +266,10 @@ def add_spec_view(
     :param filepath: absolute/relative path to the specification file
     :param route: URL path where to serve specification file
     :param route_name: Route name under which specification file will be served
+    :param route_json: URL path where to serve the specification as JSON. If not
+        provided, the JSON representation is not served. The route is registered
+        under ``route_name`` suffixed with ``_json``; not available on
+        `add_spec_view_directory`.
     :param permission: Permission for the spec view
     """
 
@@ -289,6 +294,20 @@ def spec_view(request: Request) -> FileResponse:
         config.add_route(route_name, route)
         config.add_view(route_name=route_name, permission=permission, view=spec_view)
 
+        if route_json is not None:
+            route_name_json = f"{route_name}_json"
+            spec_json = json.dumps(spec_dict)
+
+            def spec_view_json(request: Request) -> Response:
+                return Response(
+                    spec_json, content_type="application/json", charset="UTF-8"
+                )
+
+            config.add_route(route_name_json, route_json)
+            config.add_view(
+                route_name=route_name_json, permission=permission, view=spec_view_json
+            )
+
         config.registry.settings[apiname] = _create_api_settings(
             config, filepath, route_name, spec
         )

pyramid_openapi3/tests/test_views.py

@@ -16,6 +16,7 @@
 from pyramid.testing import testConfig
 from pyramid_openapi3.exceptions import RequestValidationError
 
+import json
 import os
 import pytest
 import tempfile
@@ -126,6 +127,61 @@ def test_add_spec_view() -> None:
             assert view(request=None, context=None).body == MINIMAL_DOCUMENT
 
 
+def test_add_spec_view_json_not_served_by_default() -> None:
+    """Test that the JSON spec route is not registered unless opted in."""
+    with testConfig() as config:
+        config.include("pyramid_openapi3")
+
+        with tempfile.NamedTemporaryFile() as document:
+            document.write(MINIMAL_DOCUMENT)
+            document.seek(0)
+
+            config.pyramid_openapi3_spec(
+                document.name, route="/foo.yaml", route_name="foo_api_spec"
+            )
+
+            # no route registered for the (guessed) json variant
+            route_request = config.registry.queryUtility(
+                IRouteRequest, name="foo_api_spec_json"
+            )
+            assert route_request is None
+
+
+def test_add_spec_view_json() -> None:
+    """Test registration of a view that serves the openapi document as JSON."""
+    with testConfig() as config:
+        config.include("pyramid_openapi3")
+
+        with tempfile.NamedTemporaryFile() as document:
+            document.write(MINIMAL_DOCUMENT)
+            document.seek(0)
+
+            config.pyramid_openapi3_spec(
+                document.name,
+                route="/foo.yaml",
+                route_name="foo_api_spec",
+                route_json="/foo.json",
+            )
+
+            # assert route
+            mapper = config.registry.getUtility(IRoutesMapper)
+            routes = mapper.get_routes()
+            assert routes[1].name == "foo_api_spec_json"
+            assert routes[1].path == "/foo.json"
+
+            # assert view
+            request = config.registry.queryUtility(
+                IRouteRequest, name="foo_api_spec_json"
+            )
+            view = config.registry.adapters.registered(
+                (IViewClassifier, request, Interface), IView, name=""
+            )
+            response = view(request=None, context=None)
+            assert response.content_type == "application/json"
+            spec = config.registry.settings["pyramid_openapi3"]["spec"]
+            assert json.loads(response.body) == spec.read_value()
+
+
 def test_add_spec_view_already_defined() -> None:
     """Test that creating a spec more than once raises an Exception."""
     with testConfig() as config: