Skip to content

Sugar Parameters

The following is an introduction to Sugar parameters.

Flask Parameters

If you want to know what these parameters do, see the flask documentation.

Parameter Type
import_name str
static_url_path str
static_folder str
static_host str
host_matching bool
subdomain_matching bool
template_folder str
instance_path str
instance_relative_config bool
root_path str

Metadata for API

You can set the following fields that are used in the OpenAPI specification and the automatic API docs UIs:

Parameter Type Description
title str The title of the API.
description str A short description of the API. It can use Markdown.
doc_version string The version of the API. This is the version of your own application, not of OpenAPI. For example 2.5.0.
terms_service str A URL to the Terms of Service for the API. If provided, this has to be a URL.
contact dict The contact information for the exposed API. It can contain several fields.
contact fields
ParameterTypeDescription
namestrThe identifying name of the contact person/organization.
urlstrThe URL pointing to the contact information. MUST be in the format of a URL.
emailstrThe email address of the contact person/organization. MUST be in the format of an email address.
license_ dict The license information for the exposed API. It can contain several fields.
license_ fields
ParameterTypeDescription
namestrREQUIRED (if a license_ is set). The license name used for the API.
urlstrA URL to the license used for the API. MUST be in the format of a URL.
servers list An array of Server Objects, which provide connectivity information to a target server. If the servers property is not provided, or is an empty array, the default value would be a Server Object with a url value of /.
security_schemes dict Defines a security scheme that can be used by the operations. Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), OAuth2's common flows (implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery.
security_schemes fields
ParameterTypeDescription
typestrREQUIRED. The type of the security scheme. Valid values are "apiKey", "http", "oauth2", "openIdConnect".
descriptionstrA short description for security scheme. CommonMark syntax MAY be used for rich text representation.
namestr REQUIRED. The name of the header, query or cookie parameter to be used.
instr REQUIRED. The location of the API key. Valid values are "query", "header" or "cookie".
etc
enable_doc bool Enable API document, default True
cache_openapi_json bool Whether to cache OpenAPI json, default True
doc_route_filter DocRouteFilter API Documentation Route Filter

Tip

more info in swagger documentation

You can set them as follows:

from flask_sugar import Sugar

description = """
YangGeApp API helps you do awesome stuff. 🚀

## Items

You can **read items**.

## Users

You will be able to:

* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
"""

app = Sugar(
    __name__,
    title="YangGeApp",
    description=description,
    doc_version="0.0.1",
    terms_service="http://localhost/terms/",
    contact={
        "name": "YangGe Team",
        "url": "http://localhost/contact/",
        "email": "example@example.com",
    },
    license_={
        "name": "Apache 2.0",
        "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
    },
    servers=[
        {
            "url": "http://127.0.0.1:5000/",
            "description": "Development server",
        },
        {
            "url": "http://localhost:5000/",
            "description": "Staging server",
        },
    ],
    security_schemes={
        "http basic": {
            "type": "http",
            "scheme": "basic"
        },
        "api key": {
            "type": "apiKey",
            "name": "api_key",
            "in": "header"
        }
    }
)


@app.get("/items/")
def read_items():
    return {"name": "YangGe"}

Tip

You can write Markdown in the description field and it will be rendered in the output.

With this configuration, the automatic API docs would look like:

Metadata for tags

You can also add additional metadata for the different tags used to group your path operations with the parameter tags.

It takes a list containing one dictionary for each tag.

Each dictionary can contain:

  • name (required): a str with the same tag name you use in the tags parameter in your path operations and Blueprints.
  • description: a str with a short description for the tag. It can have Markdown and will be shown in the docs UI.
  • externalDocs: a dict describing external documentation with:
    • description: a str with a short description for the external docs.
    • url (required): a str with the URL for the external documentation.

Create metadata for tags

Let's try that in an example with tags for users and items.

Create metadata for your tags and pass it to the tags parameter:

from flask_sugar import Sugar

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://shangsky.github.io/flask-sugar",
        },
    },
]

app = Sugar(__name__, tags=tags_metadata)


@app.get("/users/", tags=["users"])
def get_users():
    return {"users": [{"name": "Harry"}, {"name": "Ron"}]}


@app.get("/items/", tags=["items"])
def get_items():
    return {"items": [{"name": "wand"}, {"name": "flying broom"}]}

Notice that you can use Markdown inside of the descriptions, for example "login" will be shown in bold (login) and "fancy" will be shown in italics (fancy).

Tip

You don't have to add metadata for all the tags that you use.

Use your tags

Use the tags parameter with your path operations (and Blueprints) to assign them to different tags:

from flask_sugar import Sugar

tags_metadata = [
    {
        "name": "users",
        "description": "Operations with users. The **login** logic is also here.",
    },
    {
        "name": "items",
        "description": "Manage items. So _fancy_ they have their own docs.",
        "externalDocs": {
            "description": "Items external docs",
            "url": "https://shangsky.github.io/flask-sugar",
        },
    },
]

app = Sugar(__name__, tags=tags_metadata)


@app.get("/users/", tags=["users"])
def get_users():
    return {"users": [{"name": "Harry"}, {"name": "Ron"}]}


@app.get("/items/", tags=["items"])
def get_items():
    return {"items": [{"name": "wand"}, {"name": "flying broom"}]}

Check the docs

Now, if you check the docs, they will show all the additional metadata:

Order of tags

The order of each tag metadata dictionary also defines the order shown in the docs UI.

For example, even though users would go after items in alphabetical order, it is shown before them, because we added their metadata as the first dictionary in the list.

Docs Url Parameters

Parameter Type Description
openapi_url_prefix str The prefix of the api documentation. example: openapi_url_prefix=/abc, you should visit the doct at /abc/doc and /abc/redoc.
openapi_json_url str The url of openapi.json, if openapi_json_url=None, api doc will close
swagger_url str The url of the swagger doc.
redoc_url str The url of the redoc.
swagger_js_url str The staic js file url of swagger ui.
swagger_css_url str The staic css file url of swagger ui.
redoc_js_url str The staic js file url of redoc.
Back to top