構成コード
@Configuration
// @Profile()
public class SwaggerConfig {
@Bean
public OpenAPI springShopOpenAPI() {
return new OpenAPI()
.components(components())
// 2. 再在这里添加上Swagger要使用的安全策略
// addList()中写上对应的key
.addSecurityItem(new SecurityRequirement().addList("tokenScheme"));
}
// 1. 先在组件中注册安全策略
private Components components(){
return new Components()
// 第一个参数是key值，后面是初始化一个安全策略的参数
.addSecuritySchemes("tokenScheme", new SecurityScheme().type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).name("token"));
}
}
Swagger ページを開くと、効果は次のようになります。
右側に追加のロック記号があり、クリックしてトークン値を出力します。
[Authorize] をクリックすると、送信されたリクエストによってフィールドがトークンとしてリクエスト ヘッダーに自動的に追加され、その値が入力値になります。
参照リンク: springdoc-openapi-ui は、JWT リクエスト ヘッダー パラメータを追加して、swagger を生成します
セキュリティ ポリシーの種類 SecurityScheme.Type
セキュリティ ポリシーを初期化するときは、さまざまなタイプを選択できることに注意してください。
上記の例ではapiKeyタイプを使用し、apiKey の場所を指定しており、リクエストが送信されるたびに apiKey を自動的に割り当てることができます。
上の写真のように、これ以外にもhttpやその他の種類があり、作者は当分触れていないので説明は割愛しますが、この http のセキュリティ ポリシーとは何なのでしょうか。次は一緒に探しましょう。
http セキュリティ ポリシー
httpプロトコルではセキュリティ認証方式も定義されていますが、実際にはあまり使われていないのであまり聞かないかもしれません。
WWW 認証フィールド
応答で 401 ステータス コードを返し、 WWW-AuthenticateUnauthorized フィールドを返して、インターフェイスがアクセスするための承認が必要であることをクライアントに伝え、ID 認証方式の使用などの関連情報を WWW-Authenticate フィールドに指定できます。
詳細については、MDN ドキュメント: WWW-Authenticateを参照してください。
一般的な ID 認証方式にはBasic、Bearerなどがありますが、ここでは特に説明しません。
認可
これに対応して、ユーザー資格情報を返すリクエストに **Authorization** フィールドもあります。構文は次のとおりです。
Authorization: <auth-scheme> <authorization-parameters>
最初のパラメーターは使用する認証方式を指定し、2 番目のパラメーターは認証パラメーターを指定します。
詳細については、MDN ドキュメント: Authorizationを参照してください。
Swagger で練習する
要約すると、http セキュリティ ポリシーを使用する場合は、Swagger で次のように構成できます。
private Components components(){
return new Components()
.addSecuritySchemes("tokenScheme", new SecurityScheme().type(SecurityScheme.Type.APIKEY).in(SecurityScheme.In.HEADER).name("token"))
// type指定为http scheme中指定为bearer
.addSecuritySchemes("httpTest", new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer"));
}
Swagger ページは次のとおりです。
これは http セキュリティ ポリシーであるため、リクエスト ヘッダーにAuthorizationフィールドのみが含まれることに注意してください。トークン認証がリクエスト ヘッダーのカスタム フィールド トークンを直接読み取る場合、この設定は無効です。