Swaggerの本文パラメーターとして文字列の配列を指定する

投稿日: 2022-10-15 2022-10-15
タグ: Spring, Swagger

1. 概要

Swagger は、RESTAPIを文書化および説明するための一連の仕様です。また、エンドポイントパラメータの値の例も提供します。

このチュートリアルでは、 String 配列のデフォルトのサンプル値を生成する方法を示します。これは、この動作がデフォルトで有効になっていないためです。

2. Swaggerの本文パラメーターとして文字列の配列を指定する

この問題は、Swaggerで文字列の配列を本体パラメーターとして指定する場合に発生します。

Swaggerエディターでわかるように、Swaggerのデフォルトのサンプル値は少し不透明です。

したがって、ここでは、Swaggerが実際には配列の内容がどのように見えるべきかの例を示していないことがわかります。追加する方法を見てみましょう。

3. YAML

まず、YAML表記を使用してSwaggerで文字列の配列を指定することから始めます。スキーマセクションには、 type：array with itemsStringが含まれています。

APIをより適切に文書化し、ユーザーに指示するために、値の挿入方法のexampleラベルを使用できます。

parameters:
  - in: body
    description: ""
    required: true
    name: name
    schema:
      type: array
      items:
        type: string
      example: ["str1", "str2", "str3"]

ディスプレイがどのように有益になるか見てみましょう。

4. Springfox

または、Springfoxを使用して同じ結果を達成できます。

@ApiModelおよび@ApiModelProperty注釈を使用して、データモデルでdataTypeおよびexampleを使用する必要があります。

@ApiModel
public class Foo {
    private long id;
    @ApiModelProperty(name = "name", dataType = "List", example = "[\"str1\", \"str2\", \"str3\"]")
    private List<String> name;

その後、 Controller に注釈を付けて、Swaggerがデータモデルを指すようにする必要があります。

それでは、@ApiImplicitParamsを使用してみましょう。

@RequestMapping(method = RequestMethod.POST, value = "/foos")
@ResponseStatus(HttpStatus.CREATED)
@ResponseBody
@ApiImplicitParams({ @ApiImplicitParam(name = "foo", 
  value = "List of strings", paramType = "body", dataType = "Foo") })
public Foo create(@RequestBody final Foo foo) {

以上です！

5. 結論

REST APIを文書化するとき、文字列配列であるパラメーターがある場合があります。理想的には、これらをサンプル値で文書化します。

これは、の例プロパティを使用してSwaggerで実行できます。または、Springfoxのexampleannotation属性を使用できます。

いつものように、コードはGitHubでから入手できます。

getdocs

13036