adjust API docs more

.env_EXAMPLE

@@ -1,3 +1,4 @@
+ENV=develop
 BASE_URI="https://api.academyruins.com"
 ADMIN_KEY="super-secret-value"
 

app/main.py

@@ -1,4 +1,5 @@
 import logging
+import os
 import uuid
 from typing import Any, Callable
 
@@ -9,6 +10,7 @@
 
 from app.openapi import strings
 from app.openapi.openapi_decorators import (
+    ApiLogoDecorator,
     BaseResolver,
     CachingDecorator,
     Remove422Decorator,
@@ -40,6 +42,8 @@
     version="0.3.0",
     description=strings.description,
     openapi_tags=strings.tag_dicts,
+    license_info=strings.license_info,
+    contact=strings.contact_info,
     redoc_url="/docs",
     docs_url="/old_docs",
 )
@@ -70,6 +74,9 @@ def compose_api_resolver() -> Callable[[], dict[str, Any]]:
     resolver = Remove422Decorator(app.routes, resolver)
     resolver = ValidationErrorSchemaDecorator(resolver)
     resolver = TagGroupsDecorator(strings.tag_groups, resolver)
+    if os.environ.get("ENV") == "production":
+        # logos are hosted statically on develop
+        resolver = ApiLogoDecorator("https://academyruins.com/title-dark.png", "Academy Ruins logo", resolver)
     return CachingDecorator(app, resolver).get_schema
 
 

app/openapi/openapi_decorators.py

@@ -102,3 +102,17 @@ def get_schema(self) -> dict[str, Any]:
             groups_schema.append({"name": name, "tags": [t.name for t in group]})
         schema["x-tagGroups"] = groups_schema
         return schema
+
+
+class ApiLogoDecorator(OpenApiResolver):
+    """Decorator that inserts a logo into the schema"""
+
+    def __init__(self, url: str, alt_text: str, resolver: OpenApiResolver):
+        self.url = url
+        self.resolver = resolver
+        self.alt_text = alt_text
+
+    def get_schema(self) -> dict[str, Any]:
+        schema = self.resolver.get_schema()
+        schema["info"]["x-logo"] = {"url": self.url, "altText": self.alt_text}
+        return schema

app/openapi/strings.py

@@ -2,12 +2,15 @@
 
 title = "Academy Ruins API"
 
-description = """
-This API provides information about Magic: the Gathering rules and policy documents. It was
-primarily created to serve the [Academy Ruins](https://academyruins.com) project and the [Fryatog](
-https://github.com/Fryyyyy/Fryatog/) rules bot, but it has found other uses since. You can find the source for the
-project on [GitHub](https://github.com/lunakv/academyruins-api).
-"""
+description = """This API provides information about Magic: the Gathering rules and policy documents. Created
+primarily as a backend for the [Academy Ruins](https://academyruins.com) project, it now serves various apps and
+services in need of automated access to these resources. It is currently still in its prerelease stage of
+development, so some breaking changes may occur with each release and backwards compatibility isn't necessarily
+guaranteed until the 1.0 release is reached. (Though significant breaking changes should be very rare.)"""
+
+license_info = {"name": "AGPL v3.0", "url": "https://www.gnu.org/licenses/agpl-3.0.txt"}
+
+contact_info = {"name": "Project repository", "url": "https://github.com/lunakv/academyruins-api"}
 
 
 @dataclass
@@ -39,6 +42,9 @@ class Tag:
 in an error response with the status code 429 and body `{"detail": "Too many requests."}`. In such situations it is
 recommended to wait at least two seconds before resuming calls to the API.
 
+The data served by this project does not tend to change very often, so unless immediacy is of utmost importance,
+we encourage you to cache any served data for a period of at least 24 hours.
+
 Due to its large current computational complexity, the `/cr/trace` endpoint has a separate limit of 1 request per
 second. These limits are subject to change in future versions of the API.""",
 )