コード日進月歩

しんくうの技術的な小話、メモ、つれづれ、など

swaggere3.0で独自の認証用ヘッダを定義する

swagger

例えばカスタムヘッダでそこに認証用のキーを埋め込んでほしい場合などの書き方。OAuthとかBasic認証はあるのだけど、そういうポピュラーなものではなくオリジナルをやりたい場合の例。

書き方

  1. securitySchemes にtypeを apikey にした情報を定義する
  2. 利用したいエンドポイントで secure の項目を追加して指定する

実例

/user のエンドポイント に 認証用のコードとしてSECRETHEADERCODEを入れるようにヘッダに指定したい場合

securitySchemesの定義

以下の用に定義する

components:
  securitySchemes:
    API_SECRETCODE:
      type: apiKey
      description: ヘッダに乗せるシークレットキー
      in: header
      name: SECRETHEADERCODE

エンドポイントに追加

以下のように追加する

paths:
  /users:
    get:
      summary: "ユーザ情報の取得"
      tags:
        - "SelfSetting"
      security: 
        - API_SECRETCODE: []

できあがるcurl

UI上でcurlを生成すると以下のように出来上がる

curl -X GET "http://example.com/users?id=1" -H "accept: application/json" -H "SECRETHEADERCODE: xxxx"

さらにBasic認証も指定したい場合

例えばBasic認証とコードをかけ合わせたい等の場合は以下のようにする

まずはBasic認証

components:
  securitySchemes:
    API_SECRETCODE:
      type: apiKey
      description: ヘッダに乗せるシークレットキー
      in: header
      name: SECRETHEADERCODE
    BasicNinsho:
      type: http
      description: Basic認証
      scheme: basic

ANDにする場合は以下のように書く

paths:
  /users:
    get:
      summary: "プロフィール情報の取得。"
      tags:
        - "SelfSetting"
      security: 
        - API_SECRETCODE: []
        - BasicNinsho: []

そうすると以下のようにBasic認証情報がつく

curl -X GET "http://example.com/users?id=1" -H "accept: application/json" -H "SECRETHEADERCODE: xxxx" -H "Authorization: Basic bmFtZTpwYXNz"

参考リンク