データのエクスポート機能(oas yaml形式)の出力が変わった

データのエクスポート機能についてです。

データ形式: OpenAPI Spec
エクスポート範囲:
  モジュール: {利用しているモジュールの名称}
  対象: すべて
  OpenAPI Spec バージョン: OpenAPI 3.0
  ファイル形式: YAML
  Apidogの拡張パロパティとなるOpenAPIフィールド(x-apidog-***): いいえ
  APIのfolderをTagsフィールドとしてエクスポート: はい

でエクスポートした際、YAMLとしては次のようにメソッド GET, POST が同一のパスに対して定義された状態での出力を期待しているのですが、
GET メソッドのパス定義がクエリパラメータ付きになり、POST と別のパスであるかのような定義で出力されてしまいます。
数ヶ月前は、このような動作にはなりませんでした。エクスポート機能に変更が入ったのでしょうか。
この状態ですと利用している OpenAPIGenerator が期待する解釈をしませんので、修正いただきたいです。
なお、同一OAS内に複数のエンドポイントを定義していて、このようになってしまうものと、期待した定義で出力されるものとが混在する状況です。

期待する出力結果 (例)

  /Pet:
    get:
      operationId: postPet
      parameters:
         - name: name
           in: query
           description: 指定した値を name プロパティに含む Pet を検索する。
           required: false
           example: ドッグ
           schema:
             type: string
         - name: description
           in: query
           description: 指定した値を description プロパティに含む Pet を検索する。
           required: false
           example: 白
           schema:
             type: string
      responses:
        '200':
         ... (省略)
    post:
      operationId: postPet
      parameters: []
      requestBody:
        ... (省略)

現在の出力結果 (例)

  /Pet?name=ドッグ&description=白:
    get:
      operationId: postPet
      parameters:
         - name: name
           in: query
           description: 指定した値を name プロパティに含む Pet を検索する。
           required: false
           example: ドッグ
           schema:
             type: string
         - name: description
           in: query
           description: 指定した値を description プロパティに含む Pet を検索する。
           required: false
           example: 白
           schema:
             type: string
      responses:
        '200':
         ... (省略)
  /Pet:
    post:
      operationId: postPet
      parameters: []
      requestBody:
        ... (省略)

こんにちは!OAS YAMLエクスポート時にGETインターフェースのパスにクエリパラメータが結合される問題についてご報告いただきありがとうございます。

現在この問題を再現できていないため、原因を特定するために以下の情報を提供いただけますでしょうか:

  1. 使用中のApidogバージョン(右上のSettings - Aboutで確認可能)
  2. OpenAPI 3.0 YAMLをエクスポートした具体的な操作手順
  3. 可能であれば、問題が発生している画面のスクリーンショット、またはApidog形式でエクスポートしたファイル

情報をいただければすぐにエクスポートロジックを調査し、問題解決に努めます。
よろしくお願いいたします。

  1. 使用中のApidogバージョン(右上のSettings - Aboutで確認可能)
    Apidog 2.7.39
    です。

  2. OpenAPI 3.0 YAMLをエクスポートした具体的な操作手順
    設定 > データ管理 > データのエクスポート
    にて添付の設定でエクスポートを行っています。

  3. 可能であれば、問題が発生している画面のスクリーンショット、またはApidog形式でエクスポートしたファイル
    この場で内容をご提供することが難しいです。
    事象が発生しているプロジェクトIDをお伝えする形でみていただくことはできますでしょうか。

Web版(Apidog を教えていただければ調査いたします。

Web版でも事象の発生を確認しました。
そして、UI をよくよく見直したところ、原因も分かりました。ごめんなさい。

クエリパラメータの定義部に存在している「固定パラメータ値」のチェックが予期せずONになっていました。
これまでは偶然、「サンプル値」に何も記載していなかったため、事象が発生していなかったのですが、
最近、しっかりと例を提示しようということで「サンプル値」に値を入力したところで事象が発生していました。

「固定パラメータ値」をOFFにして本件事象の発生を回避するようにいたします。

その一方で、Apidog が出力する Open API Spec の Paths Object にクエリパラメータを含んでしまっている動作については、ちょっと引っかかっています。
RFC3986 RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax での 「Path」の定義が、クエリパラメータの開始を示す ? の前まで、ということになっているため、「Path」という用語にはクエリパラメータを含まない認識です。
Open API Spec の Paths Object の説明に、クエリパラメータを含んではならないという記述はありませんが、RFCの「Path」の定義に従うと、Paths Object にクエリパラメータ付きの文字列を設定することはせず、クエリパラメータは Parameter Object にて定義すべきと考えています。

特定のクエリパラメータ・値が指定された場合にだけ、レスポンスの定義を異なるものにもできるようにしたい、というような要望があり、それに対応するための苦肉の策なのかもと感じてはいますが。


Yusuke Maehama様

貴重なフィードバックをいただきありがとうございます。GETインターフェースのパスにクエリパラメータが結合されて出力される問題について、現在調査を進めております。問題を再現し、迅速に修正いたします。

こんにちは。Fixed ValueはApidogの機能であり、完全にはOpenAPI仕様に準拠していません。詳細はApidog公式ドキュメントをご参照ください:Endpoint unique identification - Apidog Docs