説明
HTTPヘッダー名は大文字と小文字を区別しません。同じリクエストでtokenとTokenを別々のヘッダーとして定義すると、異なる値を渡せると誤解される場合があります。
想定される影響
文書や生成クライアントが同じヘッダーを重複管理したり、異なる意味を割り当てたりして、連携に問題が生じる場合があります。
対処方法
各リクエストに適用するヘッダーを一貫した一つの定義で管理してください。別の値が必要なら、実際のAPIが区別する異なる名前を使ってください。再利用定義の一覧にある類似項目と、一つのリクエストに同時適用する重複を区別してください。
例
OpenAPI 3.0のパス単位のパラメーター一覧の抜粋です。infoと実際の操作を省略しており、認証設定全体を示すものではありません。
変更前
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"parameters": [
{
"name": "token",
"in": "header",
"schema": {
"type": "string"
}
},
{
"name": "Token",
"in": "header",
"schema": {
"type": "string"
}
}
]
}
}
}
変更後
json
{
"openapi": "3.0.0",
"paths": {
"/": {
"parameters": [
{
"name": "token",
"in": "header",
"schema": {
"type": "string"
}
},
{
"name": "username",
"in": "header",
"schema": {
"type": "string"
}
}
]
}
}
}
変更前のtokenとTokenはHTTPでは同じヘッダー名です。変更後のusernameは、サーバーが別のユーザー名ヘッダーを実際に受け付ける場合に限り適切です。同じトークンを指すなら、二つ目の定義を削除してください。