feature: Support passing custom OpenAPI versions.

.gitignore

@@ -11,5 +11,6 @@
 *.egg-info
 /dist
 /venv
+/.venv
 .mypy_cache/
 .DS_Store

aiohttp_apispec/aiohttp_apispec.py

@@ -24,12 +24,12 @@ def __init__(
         app=None,
         request_data_name="data",
         swagger_path=None,
-        static_path='/static/swagger',
+        static_path="/static/swagger",
         **kwargs
     ):
 
         self.plugin = MarshmallowPlugin()
-        self.spec = APISpec(plugins=(self.plugin,), openapi_version="2.0", **kwargs)
+        self.spec = APISpec(plugins=(self.plugin,), **kwargs)
 
         self.url = url
         self.swagger_path = swagger_path
@@ -61,17 +61,17 @@ async def swagger_handler(request):
         if self.swagger_path is not None:
             self.add_swagger_web_page(app, self.static_path, self.swagger_path)
 
-    def add_swagger_web_page(self, app: web.Application, static_path: str, view_path: str):
+    def add_swagger_web_page(
+        self, app: web.Application, static_path: str, view_path: str
+    ):
         static_files = Path(__file__).parent / "static"
         app.router.add_static(static_path, static_files)
 
         with open(str(static_files / "index.html")) as swg_tmp:
             tmp = Template(swg_tmp.read()).render(path=self.url, static=static_path)
 
         async def swagger_view(_):
-            return web.Response(
-                text=tmp, content_type="text/html"
-            )
+            return web.Response(text=tmp, content_type="text/html")
 
         app.router.add_route("GET", view_path, swagger_view)
 
@@ -148,10 +148,11 @@ def setup_aiohttp_apispec(
     *,
     title: str = "API documentation",
     version: str = "0.0.1",
+    openapi_version: str = "2.0",
     url: str = "/api/docs/swagger.json",
     request_data_name: str = "data",
     swagger_path: str = None,
-    static_path: str = '/static/swagger',
+    static_path: str = "/static/swagger",
     **kwargs
 ) -> None:
     """
@@ -195,6 +196,7 @@ async def index(request):
     :param Application app: aiohttp web app
     :param str title: API title
     :param str version: API version
+    :param str openapi_version: OpenAPI version to use. By default: ``'2.0'``
     :param str url: url for swagger spec in JSON format
     :param str request_data_name: name of the key in Request object
                                   where validated data will be placed by
@@ -211,6 +213,7 @@ async def index(request):
         request_data_name,
         title=title,
         version=version,
+        openapi_version=openapi_version,
         swagger_path=swagger_path,
         static_path=static_path,
         **kwargs

tests/conftest.py

@@ -13,12 +13,12 @@
 
 def pytest_report_header(config):
     return """
-          .   .  .                                   
-,-. . ,-. |-. |- |- ,-.    ,-. ,-. . ,-. ,-. ,-. ,-. 
-,-| | | | | | |  |  | | -- ,-| | | | `-. | | |-' |   
-`-^ ' `-' ' ' `' `' |-'    `-^ |-' ' `-' |-' `-' `-' 
-                    |          |         |           
-                    '          '         '           
+          .   .  .
+,-. . ,-. |-. |- |- ,-.    ,-. ,-. . ,-. ,-. ,-. ,-.
+,-| | | | | | |  |  | | -- ,-| | | | `-. | | |-' |
+`-^ ' `-' ' ' `' `' |-'    `-^ |-' ' `-' |-' `-' `-'
+                    |          |         |
+                    '          '         '
     """
 
 
@@ -55,10 +55,22 @@ class ResponseSchema(Schema):
 
 @pytest.fixture(
     params=[
-        ({"locations": ["query"]}, True),
-        ({"location": "query"}, True),
-        ({"locations": ["query"]}, False),
-        ({"location": "query"}, False),
+        (None, {"locations": ["query"]}, True),
+        (None, {"location": "query"}, True),
+        (None, {"locations": ["query"]}, False),
+        (None, {"location": "query"}, False),
+        ("2.0", {"locations": ["query"]}, True),
+        ("2.0", {"location": "query"}, True),
+        ("2.0", {"locations": ["query"]}, False),
+        ("2.0", {"location": "query"}, False),
+        ("2.1", {"locations": ["query"]}, True),
+        ("2.1", {"location": "query"}, True),
+        ("2.1", {"locations": ["query"]}, False),
+        ("2.1", {"location": "query"}, False),
+        ("3.0", {"locations": ["query"]}, True),
+        ("3.0", {"location": "query"}, True),
+        ("3.0.2", {"locations": ["query"]}, True),
+        ("3.0.2", {"location": "query"}, True),
     ]
 )
 def aiohttp_app(
@@ -69,7 +81,7 @@ def aiohttp_app(
     aiohttp_client,
     request,
 ):
-    locations, nested = request.param
+    openapi_version, locations, nested = request.param
 
     @docs(
         tags=["mytag"],
@@ -127,10 +139,18 @@ async def other(request):
         return web.Response()
 
     app = web.Application()
+    kwargs = {}
+    if openapi_version:
+        kwargs["openapi_version"] = openapi_version
+
     if nested:
         v1 = web.Application()
         setup_aiohttp_apispec(
-            app=v1, title="API documentation", version="0.0.1", url="/api/docs/api-docs"
+            app=v1,
+            title="API documentation",
+            version="0.0.1",
+            url="/api/docs/api-docs",
+            **kwargs,
         )
         v1.router.add_routes(
             [
@@ -147,7 +167,7 @@ async def other(request):
         v1.middlewares.append(validation_middleware)
         app.add_subapp("/v1/", v1)
     else:
-        setup_aiohttp_apispec(app=app, url="/v1/api/docs/api-docs")
+        setup_aiohttp_apispec(app=app, url="/v1/api/docs/api-docs", **kwargs)
         app.router.add_routes(
             [
                 web.get("/v1/test", handler_get),