diff --git a/docs/source/tour.rst b/docs/source/tour.rst index 051a007..475c1c5 100644 --- a/docs/source/tour.rst +++ b/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") diff --git a/responder/api.py b/responder/api.py index 9388105..926379b 100644 --- a/responder/api.py +++ b/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, diff --git a/tests/test_responder.py b/tests/test_responder.py index 7048d1b..1cb29c0 100644 --- a/tests/test_responder.py +++ b/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", ";"], )