Operations parameters
Doc Enable
You can set doc_enable=False
to hide the doc of current api
from flask_sugar import Sugar
app = Sugar(__name__)
@app.get("/demo1", doc_enable=False)
def demo1():
return {"code": 0}
@app.get("/demo2")
def demo2():
return {"code": 0}
Tags
You can group your API operations using the tags
argument (list[str]
).
from flask_sugar import Sugar
app = Sugar(__name__)
@app.get("/demo1")
def demo1():
return {"code": 0}
@app.get("/demo2", tags=["Hello"])
def demo2():
return {"code": 0}
Tagged operations may be handled differently by various tools and libraries. For example, the Swagger UI uses tags to group the displayed operations.
Blueprint tags
You can use tags
argument to apply tags to all operations declared by Blueprint, Routes inherit the Blueprint's tags, you can set extends_tags=False
to disable it:
from flask_sugar import Sugar, Blueprint
app = Sugar(__name__)
hello_bp = Blueprint("hello", __name__, tags=["world"])
@hello_bp.get("/demo1")
def demo1():
return {"code": 0}
@hello_bp.get("/demo2", extends_tags=False)
def demo2():
return {"code": 0}
app.register_blueprint(hello_bp)
Note
the Blueprint tags default value is [name of the Blueprint
]
Summary
Summary is a human-readable name for your operation.
By default, it's generated by capitalizing your operation function name:
from flask_sugar import Sugar
app = Sugar(__name__)
@app.get("/hello/")
def hello(name: str):
return {"hello": name}
If you want to override it or translate it to other language, use the summary
argument in the api
decorator.
from flask_sugar import Sugar
app = Sugar(__name__)
@app.get("/hello/", summary="Say Hello")
def hello(name: str):
return {"hello": name}
Description
If you need to provide more information about your operation, use either the description
argument or normal Python docstrings:
@app.get("/hello/", description="say hello to any one")
def hello(name: str):
return {"hello": name}
When you need to provide a long multi line description, you can use Python docstrings
for the function definition:
@app.get("/hello/")
def hello(name: str):
"""
Say Hello:
- hello
- world
"""
return {"hello": name}
Response Description
If you need to provide more information about your response, use either the response_description
argument:
@app.get("/hello/", response_description="Success Response")
def hello(name: str):
return {"hello": name}
Deprecated
If you need to mark an operation as deprecated without removing it, use the deprecated
argument:
@app.get("/hello/", deprecated=True)
def hello(name: str):
return {"hello": name}
It will be marked as deprecated in the JSON Schema and also in the interactive OpenAPI docs:
OperationId
The OpenAPI operationId
is an optional unique string used to identify an operation. If provided, these IDs must be unique among all operations described in your API.
By default, Flask Sugar sets it to view endpoint
+ __
+ http method in lower
.
If you want to set it individually for each operation, use the operation_id
argument:
@app.post("/tasks", operation_id="create_task")
def new_task():
...
Security
A declaration of which security mechanisms can be used for this operation. The list of values includes alternative security requirement objects that can be used. Only one of the security requirement objects need to be satisfied to authorize a request. To make security optional, an empty security requirement ({}) can be included in the array. This definition overrides any declared top-level security. To remove a top-level security declaration, an empty array can be used.
Extra
The rest of the Operation properties can override all the properties previously set