wip: document meme responses

app/config.py

@@ -40,16 +40,16 @@ def init(app):
         "https://github.com/jacebrowning/memegen/blob/main/LICENSE.txt"
     )
 
-    app.ext.openapi.add_security_scheme("ApiKeyAuth", type="apiKey", name="X-API-KEY")
-    app.ext.openapi.secured("ApiKeyAuth")
-
     app.config.OAS_UI_DEFAULT = "swagger"
     app.config.OAS_UI_REDOC = False
     app.config.SWAGGER_UI_CONFIGURATION = {
         "operationsSorter": "alpha",
         "docExpansion": "list",
     }
 
+    app.ext.openapi.add_security_scheme("ApiKeyAuth", type="apiKey", name="X-API-KEY")
+    app.ext.openapi.secured("ApiKeyAuth")
+
     app.blueprint(views.clients.blueprint)
     app.blueprint(views.memes.blueprint)
     app.blueprint(views.templates.blueprint)

app/views/memes.py

@@ -11,6 +11,12 @@
 blueprint = Blueprint("Memes", url_prefix="/images")
 
 
+@dataclass
+class ExampleResponse:
+    url: str
+    template: str
+
+
 @blueprint.get("/")
 @openapi.summary("List example memes")
 @openapi.operation("Memes.list")
@@ -19,7 +25,7 @@
 )
 @openapi.response(
     200,
-    {"application/json": list({"url": str, "template": str})},
+    {"application/json": list[ExampleResponse]},
     "Successfully returned a list of example memes",
 )
 async def index(request):
@@ -40,16 +46,30 @@ class MemeRequest:
     redirect: bool
 
 
+@dataclass
+class MemeResponse:
+    url: str
+
+
+@dataclass
+class ErrorResponse:
+    error: str
+
+
 @blueprint.post("/")
 @openapi.summary("Create a meme from a template")
 @openapi.operation("Memes.create")
 @openapi.body({"application/json": MemeRequest})
-@openapi.response(201, {"url": str}, description="Successfully created a meme")
 @openapi.response(
-    400, {"error": str}, description='Required "template_id" missing in request body'
+    201, {"application/json": MemeResponse}, "Successfully created a meme"
+)
+@openapi.response(
+    400,
+    {"application/json": ErrorResponse},
+    'Required "template_id" missing in request body',
 )
 @openapi.response(
-    404, {"error": str}, description='Specified "template_id" does not exist'
+    404, {"application/json": ErrorResponse}, 'Specified "template_id" does not exist'
 )
 async def create(request):
     return await generate_url(request, template_id_required=True)
@@ -66,9 +86,11 @@ class AutomaticRequest:
 @openapi.exclude(not settings.REMOTE_TRACKING_URL)
 @openapi.summary("Create a meme from word or phrase")
 @openapi.body({"application/json": AutomaticRequest})
-@openapi.response(201, {"url": str}, description="Successfully created a meme")
 @openapi.response(
-    400, {"error": str}, description='Required "text" missing in request body'
+    201, {"application/json": MemeResponse}, "Successfully created a meme"
+)
+@openapi.response(
+    400, {"application/json": ErrorResponse}, 'Required "text" missing in request body'
 )
 async def automatic(request):
     if request.form:
@@ -114,7 +136,9 @@ class CustomRequest:
 @openapi.summary("Create a meme from any image")
 @openapi.body({"application/json": CustomRequest})
 @openapi.response(
-    201, {"url": str}, description="Successfully created a meme from a custom image"
+    201,
+    {"application/json": MemeResponse},
+    description="Successfully created a meme from a custom image",
 )
 async def custom(request):
     return await generate_url(request)

app/views/templates.py

@@ -78,6 +78,11 @@ class MemeRequest:
     redirect: bool
 
 
+@dataclass
+class MemeResponse:
+    url: str
+
+
 @blueprint.post("/<id:slug>")
 @openapi.tag("Memes")
 @openapi.operation("Memes.create_from_template")
@@ -86,7 +91,9 @@ class MemeRequest:
 @openapi.parameter("id", str, "path")
 @openapi.body({"application/json": MemeRequest})
 @openapi.response(
-    201, {"url": str}, description="Successfully created a meme from a template"
+    201,
+    {"application/json": MemeResponse},
+    "Successfully created a meme from a template",
 )
 async def build(request, id):
     return await generate_url(request, id)
@@ -108,7 +115,9 @@ class CustomRequest:
 @openapi.summary("Create a meme from any image" + settings.SUFFIX)
 @openapi.body({"application/json": CustomRequest})
 @openapi.response(
-    201, {"url": str}, description="Successfully created a meme from a custom image"
+    201,
+    {"application/json": MemeResponse},
+    "Successfully created a meme from a custom image",
 )
 async def custom(request):
     return await generate_url(request)