api OpenAPI params match /docs display order, updated tour docs and docs test

docs/source/tour.rst

@@ -63,7 +63,28 @@ Responder comes with built-in support for OpenAPI / marshmallow::
     import responder
     from marshmallow import Schema, fields
 
-    api = responder.API(title="Web Service", version="1.0", openapi="3.0.0")
+    description = "This is a sample server for a pet store."
+    terms_of_service = "http://example.com/terms/"
+    contact = {
+        "name": "API Support",
+        "url": "http://www.example.com/support",
+        "email": "support@example.com",
+    }
+    license = {
+        "name": "Apache 2.0",
+        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
+    }
+
+    api = responder.API(
+        title="Web Service",
+        version="1.0",
+        openapi="3.0.2",
+        docs_route='/docs',
+        description=description,
+        terms_of_service=terms_of_service,
+        contact=contact,
+        license=license,
+    )
 
 
     @api.schema("Pet")

responder/api.py

@@ -48,16 +48,10 @@ class API:
         :param enable_hsts: If ``True``, send all responses to HTTPS URLs.
         :param title: The title of the application (OpenAPI Info Object)
         :param version: The version of the OpenAPI document (OpenAPI Info Object)
-        :param contact: The contact dictionary of the application (OpenAPI Contact Object)
-                    e.g. {
-                          "name": "API Support",
-                          "url": "http://www.example.com/support",
-                          "email": "support@example.com"
-                          }
-        :param license: The license information of the exposed API (OpenAPI License Object)
-                    e.g. {"name": "Apache 2.0",
-                          "url": "https://www.apache.org/licenses/LICENSE-2.0.html"}
+        :param description: The description of the OpenAPI document (OpenAPI Info Object)
         :param terms_of_service: A URL to the Terms of Service for the API (OpenAPI Info Object)
+        :param contact: The contact dictionary of the application (OpenAPI Contact Object)
+        :param license: The license information of the exposed API (OpenAPI License Object)
     """
 
     status_codes = status_codes
@@ -68,10 +62,10 @@ class API:
         debug=False,
         title=None,
         version=None,
-        contact=None,
-        license=None,
         description=None,
         terms_of_service=None,
+        contact=None,
+        license=None,
         openapi=None,
         openapi_route="/schema.yml",
         static_dir="static",
@@ -90,10 +84,10 @@ class API:
         self.secret_key = secret_key
         self.title = title
         self.version = version
-        self.contact = contact
-        self.license = license
         self.description = description
         self.terms_of_service = terms_of_service
+        self.contact = contact
+        self.license = license
         self.openapi_version = openapi
         self.static_dir = Path(os.path.abspath(static_dir))
         self.static_route = f"/{static_route.strip('/')}"
@@ -197,14 +191,14 @@ class API:
     def _apispec(self):
 
         info = {}
-        if self.contact is not None:
-            info["contact"] = self.contact
-        if self.license is not None:
-            info["license"] = self.license
         if self.description is not None:
             info["description"] = self.description
         if self.terms_of_service is not None:
             info["termsOfService"] = self.terms_of_service
+        if self.contact is not None:
+            info["contact"] = self.contact
+        if self.license is not None:
+            info["license"] = self.license
 
         spec = APISpec(
             title=self.title,

tests/test_responder.py

@@ -336,7 +336,7 @@ def test_schema_generation():
     from marshmallow import Schema, fields
 
     api = responder.API(
-        title="Web Service", openapi="3.0", allowed_hosts=["testserver", ";"]
+        title="Web Service", openapi="3.0.2", allowed_hosts=["testserver", ";"]
     )
 
     @api.schema("Pet")
@@ -361,17 +361,34 @@ def test_schema_generation():
     dump = yaml.safe_load(r.content)
 
     assert dump
-    assert dump["openapi"] == "3.0"
+    assert dump["openapi"] == "3.0.2"
 
 
 def test_documentation():
     import responder
     from marshmallow import Schema, fields
 
+    description = "This is a sample server for a pet store."
+    terms_of_service = "http://example.com/terms/"
+    contact = {
+        "name": "API Support",
+        "url": "http://www.example.com/support",
+        "email": "support@example.com",
+    }
+    license = {
+        "name": "Apache 2.0",
+        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
+    }
+
     api = responder.API(
         title="Web Service",
-        openapi="3.0",
+        version="1.0",
+        openapi="3.0.2",
         docs_route="/docs",
+        description=description,
+        terms_of_service=terms_of_service,
+        contact=contact,
+        license=license,
         allowed_hosts=["testserver", ";"],
     )