SwaggerAPIでリクエストフィールドを非表示にする
1. 概要
Swagger UI をプラットフォームとして使用して、APIインターフェースを視覚化して便利な方法で操作できます。 これは、最小限の構成でAPI構造を生成するための強力なツールです。
この記事では、SwaggerとSpring BootRESTAPIの使用に焦点を当てます。 具体的には、SwaggerUIでリクエストフィールドを非表示にするさまざまな方法について説明します。
2. 序章
簡単にするために、基本的なSpring Bootアプリケーションを作成し、SwaggerUIを使用してAPIを調べます。
SpringBootを使用して簡単なArticleApplicationを作成しましょう。 ArticlesControllerを使用して2つのAPIを公開しています。 GET APIを使用して、すべての記事に関連する詳細を受け取りたいと考えています。
一方、 POST APIを使用して、新しい記事の詳細を追加します。
@RestController
@RequestMapping("/articles")
public class ArticlesController {
@Autowired
private ArticleService articleService;
@GetMapping("")
public List<Article> getAllArticles() {
return articleService.getAllArticles();
}
@PostMapping("")
public void addArticle(@RequestBody Article article) {
articleService.addArticle(article);
}
}
これらのAPIのデータ転送オブジェクト(DTO)としてArticleクラスを使用します。 それでは、Articleクラスにいくつかのフィールドを追加しましょう。
public class Article {
private int id;
private String title;
private int numOfWords;
// standard getters and setters
}
http:// localhost:8080 / swagger-ui /#/articles-controllerでSwaggerUIにアクセスできます。 アプリケーションを実行して、上記の2つのAPIのデフォルトの動作を見てみましょう。
POST APIでは、ユーザーからのすべての詳細( id 、 title 、 numOfWords )を受け入れています。 GET APIでは、応答で同じフィールドを返します。 デフォルトでは、両方のAPIのすべてのフィールドがSwaggerによって表示されていることがわかります。
ここで、別のバックエンドロジックを使用してidフィールドを設定するとします。 このようなシナリオでは、idフィールドに関連する情報をユーザーに入力させたくありません。 混乱を避けるために、SwaggerUIでこのフィールドを非表示にします。
私たちの頭に浮かぶ当面のオプションは、別のDTOを作成し、その中に必要なフィールドを非表示にすることです。 このメソッドは、DTOのロジックを追加する場合に役立ちます。 全体的な要件に適合する場合は、このオプションを使用することを選択できます。
この記事では、さまざまなアノテーションを使用してSwaggerUIのフィールドを非表示にしましょう。
3. @JsonIgnoreを使用する
@JsonIgnore は、標準のJacksonアノテーションです。 これを使用して、シリアル化および逆シリアル化中にJacksonがフィールドを無視するように指定できます。 無視するフィールドだけに注釈を追加すると、指定されたフィールドのゲッターとセッターの両方が非表示になります。
やるだけやってみよう:
@JsonIgnore
private int id;
アプリケーションを再実行して、SwaggerUIを調べてみましょう。
これで、idフィールドがAPIの説明に表示されていないことがわかります。 Swaggerは、同様の動作を実現するための注釈も提供します。
4. @ApiModelPropertyを使用する
@ApiModelProperty は、モデルオブジェクトのプロパティに関連するメタデータを提供します。 アノテーションのhiddenプロパティを使用して、SwaggerUIのモデルオブジェクトの定義でフィールドを非表示にすることができます。
idフィールドで試してみましょう。
@ApiModelProperty(hidden = true)
private int id;
上記のシナリオでは、idフィールドがGETAPIとPOSTAPIの両方で非表示になっていることがわかります。 ユーザーがidの詳細をGETAPI応答の一部として表示できるようにしたいとします。 この場合、他のオプションを探す必要があります。
Swaggerは、代替プロパティreadOnly、も提供します。 これを使用して、更新操作中に指定されたフィールドを非表示にし、取得操作には表示することができます。
それを調べてみましょう:
@ApiModelProperty(readOnly = true)
private int id;
更新されたSwaggerUIを今すぐ確認しましょう。
idフィールドはGET APIで表示されますが、 POSTAPIでは非表示のままです。読み取り専用をサポートします。 ] オペレーション。
このプロパティは、バージョン1.5.19で非推奨としてマークされています。 より高いバージョンについては、他の注釈を調べてみましょう。
5. @JsonPropertyを使用する
Jacksonは、@JsonPropertyアノテーションを提供します。 これを使用して、オブジェクトのシリアル化/逆シリアル化中に使用できるPOJOフィールドのゲッター/セッターに関連するメタデータを追加できます。 アノテーションのアクセスプロパティを設定して、特定のフィールドでの読み取り操作のみを許可することができます。
@JsonProperty(access = JsonProperty.Access.READ_ONLY)
private int id;
このようにして、 POSTAPIモデル定義のidフィールドを非表示にすることができますが、それでも GETAPI応答で表示できます。 目的の機能を実現するための別の方法を調べてみましょう。
6. @ApiParamを使用する
@ApiParam は、リクエストパラメーターに関連するメタデータを指定するために使用できるSwaggerアノテーションでもあります。 は、任意のプロパティを非表示にするために、hiddenプロパティをtrueに設定できます。 ただし、ここには制限があります。は、@RequestBodyの代わりに@ModelAttributeを使用してリクエストデータにアクセスする場合にのみ機能します。
試してみましょう:
@PostMapping("")
public void addArticle(@ModelAttribute Article article) {
articleService.addArticle(article);
}
@ApiParam(hidden = true)
private int id;
この場合のSwaggerUI仕様を調べてみましょう。
POSTAPIリクエストデータ定義のidフィールドを正常に非表示にすることができます。
7. 結論
SwaggerUIでモデルオブジェクトプロパティの表示を変更するためのさまざまなオプションを検討しました。 説明したアノテーションは、Swagger仕様を更新するために使用できる他のいくつかの機能も提供します。 要件に応じて適切な方法を使用する必要があります。
ソースコードは、GitHubでから入手できます。