此时，我们需要存档外部 API 的*信息*，比如应该有哪些*路径操作*，请求体应该是什么，应该返回什么响应等。

## 使用回调的应用 { #an-app-with-callbacks }

示例如下。

假设要开发一个创建发票的应用。

发票包括 `id`、`title`（可选）、`customer`、`total` 等属性。

API 的用户（外部开发者）要在您的 API 内使用 POST 请求创建一条发票记录。

（假设）您的 API 将：

* 把发票发送至外部开发者的消费者
* 归集现金
* 把通知发送至 API 的用户（外部开发者）
    * 通过（从您的 API）发送 POST 请求至外部 API（即**回调**）来完成

			"minio.RELEASE.2016-10-07T01-16-39Z", false,
		},
		{
			"fbe246edbd382902db9a4035df7dce8cb441357d minio.RELEASE.2016-10-07T01-16-39Z.customer-hotfix\n", releaseTime, "fbe246edbd382902db9a4035df7dce8cb441357d",
			"minio.RELEASE.2016-10-07T01-16-39Z.customer-hotfix", false,
		},
	}

	for i, testCase := range testCases {
		sha256Sum, result, releaseInfo, err := parseReleaseData(testCase.data)

在這種情況下，你可能想要文件化說明該外部 API 應該長什麼樣子。它應該有哪些「路徑操作」、應該接受什麼 body、應該回傳什麼 response，等等。

## 帶有回呼的應用 { #an-app-with-callbacks }

我們用一個例子來看。

想像你開發了一個允許建立發票的應用。

這些發票會有 `id`、`title`（可選）、`customer` 和 `total`。

你的 API 的使用者（外部開發者）會透過一個 POST 請求在你的 API 中建立一張發票。

然後你的 API 會（讓我們想像）：

* 將發票寄給該外部開發者的某位客戶。
* 代收款項。
* 再把通知回傳給 API 使用者（外部開發者）。
    * 這會透過從「你的 API」向該外部開發者提供的「外部 API」送出 POST 請求完成（這就是「回呼」）。

// Package crypto implements AWS S3 related cryptographic building blocks
// for implementing Server-Side-Encryption (SSE-S3) and Server-Side-Encryption
// with customer provided keys (SSE-C).
//
// All objects are encrypted with an unique and randomly generated 'ObjectKey'.
// The ObjectKey itself is never stored in plaintext. Instead it is only stored

src_obj4_etag=$(echo "${stat_out4}" | jq '.etag')
src_obj4_size=$(echo "${stat_out4}" | jq '.size')
src_obj4_md5=$(echo "${stat_out4}" | jq '.metadata."X-Amz-Server-Side-Encryption-Customer-Key-Md5"')

# Stat the objects from replicated site
echo "Stat minio2/test-bucket/encrypted"
./mc stat --no-list minio2/test-bucket/encrypted --insecure --json

				continue
			}
			if object.IsDeleteMarker {
				log.Println("SKIPPED: DELETE marker object:", objFullPath(object))
				continue
			}
			if _, ok := object.UserMetadata["X-Amz-Server-Side-Encryption-Customer-Algorithm"]; ok {
				log.Println("SKIPPED: Objects encrypted with SSE-C do not have md5sum as ETag:", objFullPath(object))
				continue
			}

- `X-Amz-Server-Side-Encryption-Customer-Key`: Base64 encoded new key.
- `X-Amz-Copy-Source-Server-Side-Encryption-Customer-Key`: Base64 encoded current key.

Such a special COPY request is also known as S3 SSE-C key rotation.

### Server-Side Encryption with a KMS

この場合、その *外部 API* がどのようである「べき」かをドキュメント化したくなるでしょう。どんな *path operation* を持ち、どんなボディを受け取り、どんなレスポンスを返すか、などです。

## コールバックのあるアプリ { #an-app-with-callbacks }

例で見ていきます。

あなたが請求書を作成できるアプリを開発していると想像してください。

これらの請求書は `id`、`title`（任意）、`customer`、`total` を持ちます。

あなたの API の利用者（外部開発者）は、POST リクエストであなたの API に請求書を作成します。

その後、あなたの API は（仮にこうしましょう）:

* 外部開発者の顧客に請求書を送ります。
* 代金を回収します。
* API 利用者（外部開発者）に通知を送り返します。

		Description:    "Requests specifying Server Side Encryption with Customer provided keys must provide an appropriate secret key.",
		HTTPStatusCode: http.StatusBadRequest,
	},
	ErrMissingSSECustomerKeyMD5: {
		Code:           "InvalidArgument",
		Description:    "Requests specifying Server Side Encryption with Customer provided keys must provide the client calculated MD5 of the secret key.",

//     setting will be set to this value. This setting will be only applied to newly created jobs (manual changes with Active Full
//     processing possible from the customer side).
//     Optional value, default 1024, allowed values 256,512,1024,4096,8192, value defined in KB size.
//