### Use cases: external service { #use-cases-external-service }

An example could be that you have an external authentication provider that you need to call.

You send it a token and it returns an authenticated user.

              body: output
            })
  # check that only released Gradle versions are used in the wrapper
  check_wrapper:
    permissions:
      contents: read
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - name: Check used wrapper
        run: |
          set -eu

If you want to override the response from inside of the function but at the same time document the "media type" in OpenAPI, you can use the `response_class` parameter AND return a `Response` object.

The `response_class` will then be used only to document the OpenAPI *path operation*, but your `Response` will be used as is.

#### Return an `HTMLResponse` directly { #return-an-htmlresponse-directly }

For example, it could be something like:

These features are what Marshmallow was built to provide. It is a great library, and I have used it a lot before.

But it was created before there existed Python type hints. So, to define every <abbr title="the definition of how data should be formed">schema</abbr> you need to use specific utils and classes provided by Marshmallow.

/// check | Inspired **FastAPI** to

Use code to define "schemas" that provide data types and validation, automatically.

You can define the (HTTP) `status_code` to be used in the response of your *path operation*.

You can pass directly the `int` code, like `404`.

But if you don't remember what each number code is for, you can use the shortcut constants in `status`:

{* ../../docs_src/path_operation_configuration/tutorial001_py310.py hl[1,15] *}

That status code will be used in the response and will be added to the OpenAPI schema.

You can declare the type used for the response by annotating the *path operation function* **return type**.

You can use **type annotations** the same way you would for input data in function **parameters**, you can use Pydantic models, lists, dictionaries, scalar values like integers, booleans, etc.

{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *}

FastAPI will use this return type to:

When one of these security schemes uses OAuth2, you can also declare and use scopes.

Each "scope" is just a string (without spaces).

They are normally used to declare specific security permissions, for example:

* `users:read` or `users:write` are common examples.
* `instagram_basic` is used by Facebook / Instagram.
* `https://www.googleapis.com/auth/drive` is used by Google.

/// info

type rebalancePoolStatus struct {
	ID       int               `json:"id"`       // Pool index (zero-based)
	Status   string            `json:"status"`   // Active if rebalance is running, empty otherwise
	Used     float64           `json:"used"`     // Percentage used space
	Progress rebalPoolProgress `json:"progress"` // is empty when rebalance is not running
}

// rebalanceAdminStatus holds rebalance status related information exported to mc, console, etc.

    /**
     * Static factory for quota exceeded
     */
    public static SmbResourceException quotaExceeded(int errorCode, long used, long quota) {
        return new SmbResourceException(String.format("Quota exceeded: %d/%d bytes used", used, quota), errorCode, ResourceType.QUOTA,
                quota - used, 1);
    }

///

This is of course not the frontend for the final users, but it's a great automatic tool to document interactively all your API.

It can be used by the frontend team (that can also be yourself).

It can be used by third party applications and systems.

And it can also be used by yourself, to debug, check and test the same application.

## The `password` flow { #the-password-flow }