0

私は、Jersey ベースの REST API を文書化するために swagger ツールを使用しています (私が使用している swaggerui は 2014 年 6 月にダウンロードされました。この問題が後のバージョンで修正されたかどうかはわかりませんが、そのコードに多くのカスタマイズを行ったので、もう一度カスタマイズするために多くの時間を費やすことなく、最新のものをダウンロードするオプションはありません)。

これまでのところ、すべての転送オブジェクトには 1 レベルの深さのプロパティがあります (pojo は埋め込まれていません)。しかし、より複雑なオブジェクト (2 レベルの深さ) を返すレスト パスをいくつか追加したところ、オブジェクトが埋め込まれている場合、SwaggerUI が JSON モデル スキーマを展開していないことがわかりました。

以下は、swagger doc の重要な部分です。

...
{
    "path": "/user/combo",
    "operations": [{
        "method": "POST",
        "summary": "Inserts a combo (user, address)",
        "notes": "Will insert a new user and a address definition in a single step",
        "type": "UserAndAddressWithIdSwaggerDto",
        "nickname": "insertCombo",
        "consumes": ["application/json"],
        "parameters": [{
            "name": "body",
            "description": "New user and address combo",
            "required": true,
            "type": "UserAndAddressWithIdSwaggerDto",
            "paramType": "body",
            "allowMultiple": false
        }],
        "responseMessages": [{
            "code": 200,
            "message": "OK",
            "responseModel": "UserAndAddressWithIdSwaggerDto"
        }]
    }]
}
...
"models": {
    "UserAndAddressWithIdSwaggerDto": {
        "id": "UserAndAddressWithIdSwaggerDto",
        "description": "",
        "required": ["user",
        "address"],
        "properties": {
            "user": {
                "$ref": "UserDto",
                "description": "User"
            },
            "address": {
                "$ref": "AddressDto",
                "description": "Address"
            }
        }
    },

    "UserDto": {
    "id": "UserDto",
    "properties": {
        "userId": {
            "type": "integer",
            "format": "int64"
        },
        "name": {
            "type": "string"
        },...
    },

    "AddressDto": {
    "id": "AddressDto",
    "properties": {
        "addressId": {
            "type": "integer",
            "format": "int64"
        },
        "street": {
            "type": "string"
        },...
    }

}
...

埋め込まれたオブジェクトは User と Address で、json 応答に示されているように、それらのモデルは正しく作成されています。

しかし、SwaggerUI を開くと、次の情報しか表示されません。

{
  "user": "UserDto",
  "address": "AddressDto"
}

しかし、次のようなものが表示されるはずです。

{
  "user": {
    "userId": "integer",
    "name": "string",...
  },
  "address": {
    "addressId": "integer",
    "street": "string",...
  }
}

内部プロパティを展開するコードに何か問題がある可能性があります。javascript コンソールにエラーが表示されないので、これはバグだと思います。

4

1 に答える 1