OpenAPI’s Auto-Documentation

In addition to providing request-handling functionalities, defining inbound and outbound interfaces lets you benefit from auto-generated documentation with little extra effort. It is as easy as calling the init_app method on your Jeroboam app instance. This will register an internal blueprint with two endpoints. One serves the OpenaAPI documentation in JSON format, and another serves the Swagger UI.

 1from typing import List
 2from typing import Optional
 3
 4from pydantic import BaseModel
 5
 6from flask_jeroboam import Blueprint
 7from flask_jeroboam import Jeroboam
 8from flask_jeroboam import Path
 9
10
11app = Jeroboam("Jeroboam Inbound Features App")
12app.init_app()
13
14
15class TaskIn(BaseModel):
16    name: str
17    description: Optional[str] = None
18
19
20class TaskOut(TaskIn):
21    id: int
22
23
24@app.get("/health")
25def get_health():
26    return {"status": "Ok"}
27
28
29blueprint = Blueprint("tasks", __name__, tags=["tasks"])
30
31
32@blueprint.get("/tasks", response_model=List[TaskOut])
33def get_tasks(page: int = 1, per_page: int = Path(10), search: Optional[str] = None):
34    return [{"id": 1, "name": "Task 1"}, {"id": 2, "name": "Task 2"}]
35
36
37@blueprint.get("/tasks/<int:item_id>", response_model=TaskOut)
38def get_task(item_id: int):
39    return {"id": 1, "name": "Task 1"}
40
41
42@blueprint.put("/tasks", status_code=202, tags=["sensitive"])
43def create_task(task: TaskIn):
44    return {}
45
46
47@blueprint.post("/tasks/<int:item_id>", tags=["sensitive"])
48def edit_task(item_id: int, task: TaskIn):
49    return {}
50
51
52app.register_blueprint(blueprint)
53
54if __name__ == "__main__":
55    app.run(host="localhost", port=5000)

You can check it out at localhost:5000/openapi and localhost:5000/docs.

Turning it off

If you don’t want to use the auto-documentation feature, turn it off by setting the configuration JEROBOAM_REGISTER_OPENAPI flag to False.