] = None,
    *,
    scopes: Annotated[
        Sequence[str] | None,
        Doc(
            """
            OAuth2 scopes required for the *path operation* that uses this Security
            dependency.

            The term "scope" comes from the OAuth2 specification, it seems to be
            intentionally vague and interpretable. It normally refers to permissions,
            in cases to roles.

{* ../../docs_src/request_forms/tutorial001_an_py310.py hl[3] *}

## 定義 `Form` 參數 { #define-form-parameters }

以與 `Body` 或 `Query` 相同的方式建立表單參數：

{* ../../docs_src/request_forms/tutorial001_an_py310.py hl[9] *}

例如，在 OAuth2 規範的一種用法（稱為「password flow」）中，必須以表單欄位傳送 `username` 與 `password`。

該 <dfn title="規範">規範</dfn> 要求欄位名稱必須正好是 `username` 和 `password`，而且必須以表單欄位傳送，而不是 JSON。

		return "", fmt.Errorf("unable to create provider: %v", err)
	}

	// Configure an OpenID Connect aware OAuth2 client.
	oauth2Config := oauth2.Config{
		ClientID:     pro.ClientID,
		ClientSecret: pro.ClientSecret,
		RedirectURL:  pro.RedirectURL,

		// Discovery returns the OAuth2 endpoints.
		Endpoint: provider.Endpoint(),

		// "openid" is a required scope for OpenID Connect flows.

Also, the best approach was to use already existing standards.

So, before even starting to code **FastAPI**, I spent several months studying the specs for OpenAPI, JSON Schema, OAuth2, etc. Understanding their relationship, overlap, and differences.

## Design { #design }

Then I spent some time designing the developer "API" I wanted to have as a user (as a developer using FastAPI).

        form.oicAuthServerUrl = fessConfig.getSystemProperty("oic.auth.server.url", "https://accounts.google.com/o/oauth2/auth");
        form.oicTokenServerUrl = fessConfig.getSystemProperty("oic.token.server.url", "https://accounts.google.com/o/oauth2/token");
        form.oicRedirectUrl = fessConfig.getSystemProperty("oic.redirect.url", StringUtil.EMPTY);

もしあなたのAPIのセキュリティを強化したいなら、いくつかのよりよい方法があります。例を示すと、

* リクエストボディとレスポンスのためのPydanticモデルの定義を見直す。
* 依存関係に基づきすべての必要なパーミッションとロールを設定する。
* パスワードを絶対に平文で保存しない。パスワードハッシュのみを保存する。
* pwdlibやJWTトークンに代表される、よく知られた暗号化ツールを使って実装する。
* そして必要なところでは、もっと細かいパーミッション制御をOAuth2スコープを使って行う。
* ...など

それでも、例えば本番環境のような特定の環境のみで、あるいは環境変数の設定によってAPIドキュメントをどうしても無効にしたいという、非常に特殊なユースケースがあるかもしれません。

## 設定と環境変数による条件付き OpenAPI { #conditional-openapi-from-settings-and-env-vars }

## `Form`のパラメータの定義 { #define-form-parameters }

`Body`や`Query`の場合と同じようにフォームパラメータを作成します:

{* ../../docs_src/request_forms/tutorial001_an_py310.py hl[9] *}

例えば、OAuth2仕様が使用できる方法の１つ（「パスワードフロー」と呼ばれる）では、フォームフィールドとして`username`と`password`を送信する必要があります。

<dfn title="仕様">仕様</dfn>では、フィールドの名前が正確に`username`と`password`であることと、JSONではなくフォームフィールドとして送信されることを要求しています。

</blockquote>

## 調研 { #investigation }

透過實際使用這些替代方案，我得以向它們學習、汲取想法，並以我能為自己與合作開發團隊找到的最佳方式加以整合。

例如，很清楚理想上應以標準的 Python 型別提示為基礎。

同時，最佳做法就是採用現有標準。

因此，在開始撰寫 **FastAPI** 之前，我花了好幾個月研究 OpenAPI、JSON Schema、OAuth2 等規範，了解它們之間的關係、重疊與差異。

## 設計 { #design }

接著，我花時間設計作為使用者（作為使用 FastAPI 的開發者）時希望擁有的開發者「API」。

我在最受歡迎的 Python 編輯器中測試了多個想法：PyCharm、VS Code、基於 Jedi 的編輯器。

## 调研 { #investigation }

通过使用之前所有的备选方案，我有机会从它们之中学到了很多东西，获取了很多想法，并以我和我的开发团队能想到的最好方式把这些思路整合成一体。

例如，大家都清楚，在理想状态下，它应该基于标准的 Python 类型提示。

而且，最好的方式是使用现有的标准。

因此，甚至在开发 **FastAPI** 前，我就花了几个月的时间研究 OpenAPI、JSON Schema、OAuth2 等规范。深入理解它们之间的关系、重叠及区别之处。

## 设计 { #design }

然后，我又花了一些时间从用户角度（使用 FastAPI 的开发者）设计了开发者 **API**。

同时，我还在最流行的 Python 代码编辑器中测试了很多思路，包括 PyCharm、VS Code、基于 Jedi 的编辑器。

/// danger

Never store user's plaintext passwords. Always store a "secure hash" that you can then verify.

If you don't know, you will learn what a "password hash" is in the [security chapters](security/simple-oauth2.md#password-hashing).

///

## Multiple models { #multiple-models }

Here's a general idea of how the models could look like with their password fields and the places where they are used: