クエリパラメータとしてのOpenAPIJSONオブジェクト

投稿日: 2022-10-28 2022-10-28
タグ: REST

1. 概要

このチュートリアルでは、OpenAPIを使用してJSONオブジェクトをクエリパラメーターとして操作する方法を学習します。

2. OpenAPI2のパラメータのクエリ

OpenAPI2はクエリパラメータとしてオブジェクトをサポートしていません; プリミティブ値とプリミティブの配列のみがサポートされます。

そのため、代わりにJSONパラメーターを次のように定義する必要があります。ストリング。

これが実際に動作することを確認するために、バックエンドでJSONとして解析しますが、paramsというパラメーターをstringとして定義しましょう。

swagger: "2.0"
...
paths:
  /tickets:
    get:
      tags:
      - "tickets"
      summary: "Send an JSON Object as a query param"
      parameters:
      - name: "params"
        in: "path"
        description: "{\"type\":\"foo\",\"color\":\"green\"}"
        required: true
        type: "string"

したがって、代わりに：

GET http://localhost:8080/api/tickets?type=foo&color=green

私たちはします：

GET http://localhost:8080/api/tickets?params={"type":"foo","color":"green"}

3. OpenAPI3のクエリパラメータ

OpenAPI 3では、クエリパラメータとしてオブジェクトのサポートが導入されています。

JSONパラメーターを指定するには、MIMEタイプとスキーマを含むcontentセクションを定義に追加する必要があります。

openapi: 3.0.1
...
paths:
  /tickets:
    get:
      tags:
      - tickets
      summary: Send an JSON Object as a query param
      parameters:
      - name: params
        in: query
        description: '{"type":"foo","color":"green"}'
        required: true
        schema:
          type: object
          properties:
            type:
              type: "string"
            color:
              type: "string"

リクエストは次のようになります。

GET http://localhost:8080/api/tickets?params[type]=foo¶ms[color]=green

そして、実際には、それはまだ次のように見える可能性があります：

GET http://localhost:8080/api/tickets?params={"type":"foo","color":"green"}

最初のオプションでは、パラメーター検証を使用できます。これにより、要求が行われる前に何か問題があるかどうかがわかります。

2番目のオプションでは、OpenAPI2の互換性だけでなくバックエンドの制御を強化するためにそれを交換します。

4. URLエンコード

リクエストパラメータをJSONオブジェクトとして転送するというこの決定を行う際には、安全な転送を保証するために、パラメータをURLエンコードする必要があることに注意してください。

したがって、次のURLを送信するには：

GET /tickets?params={"type":"foo","color":"green"}

私たちは実際に行います：

GET /tickets?params=%7B%22type%22%3A%22foo%22%2C%22color%22%3A%22green%22%7D

5. 制限事項

また、JSONオブジェクトをクエリパラメーターのセットとして渡すことの制限に留意しましょう。

セキュリティの低下
パラメータの制限された長さ

たとえば、クエリパラメータに配置するデータが多いほど、サーバーログに表示されるデータが多くなり、機密データが公開される可能性が高くなります。

また、単一のクエリパラメータは2048文字を超えることはできません。確かに、JSONオブジェクトがそれよりも大きいシナリオを想像することはできます。実際には、JSON文字列のURLエンコードにより、ペイロードの文字数は約1000文字に制限されます。

回避策の1つは、本文でより大きなJSONオブジェクトを送信することです。このようにして、セキュリティの問題とJSONの長さの制限の両方を修正します。

実際、GETまたはPOSTはどちらもこれをサポートしています。GETを介して本文を送信する理由の1つは、APIのRESTfulセマンティクスを維持することです。

もちろん、それは少し珍しく、普遍的にサポートされていません。たとえば、一部のJavaScript HTTPライブラリでは、GETリクエストにリクエスト本文を含めることができません。

つまり、この選択は、セマンティクスとユニバーサル互換性の間のトレードオフです。

6. 結論

要約すると、この記事では、OpenAPIを使用してJSONオブジェクトをクエリパラメーターとして指定する方法を学びました。次に、バックエンドへの影響のいくつかを観察しました。

これらの例の完全なOpenAPI定義は、GitHubでから入手できます。

getdocs

13036