API update

pssecret/main.py

@@ -8,19 +8,33 @@ from pssecret.utils import get_new_key
 app = FastAPI()
 
 
-@app.post("/secret", response_model=SecretSaveResult)
+@app.post(
+    "/secret",
+    summary="Store secret",
+    description=(
+        "Submit secret, it is saved on the server, get retrieval key in response. "
+        "Use that key to retrieve your data. Key could be used only once, "
+        "so use it wisely"
+    ),
+    response_model=SecretSaveResult,
+)
 async def set_secret(data: Secret):
     new_key = await get_new_key()
     await redis.setex(new_key, 60 * 60 * 24, data.data)
 
     return {
-        "status": "saved",
+        "key": new_key,
-        "retrieval_url": f"/secret/{new_key}",
     }
 
 
 @app.get(
     "/secret/{secret_key}",
+    summary="Retrieve secret",
+    description=(
+        "Returns previously saved data if it is still on the server. "
+        "Could be the other way around in two cases: "
+        "either it has already been retrieved, either storage timeout has expired"
+    ),
     response_model=Secret,
     responses={404: {"description": "The item was not found"}},
 )

pssecret/models.py

@@ -1,10 +1,12 @@
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 
 
 class Secret(BaseModel):
-    data: str
+    data: str = Field(title="Secret", description="Some secret data")
 
 
 class SecretSaveResult(BaseModel):
-    status: str
+    key: str = Field(
-    retrieval_url: str
+        title="Retrieval key",
+        description="Key that should be used for retrieval of submitted secret",
+    )