Swaggerを使用した設定例と説明

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

1. 概要

このチュートリアルでは、Swaggerアノテーションを使用して、ドキュメントをよりわかりやすくする方法を説明します。メソッド、パラメーター、エラーコードなど、APIのさまざまな部分に説明を追加する方法を学習します。また、要求/応答の例を追加する方法についても説明します。

2. プロジェクトの設定

製品を作成および取得するためのメソッドを提供する単純なProductsAPIを作成します。

ゼロからRESTAPIを作成するには、SpringDocsのこのチュートリアルに従ってSpringBootを使用してRESTfulWebサービスを作成します。

次のステップは、プロジェクトの依存関係と構成をセットアップすることです。この記事の手順に従って、SpringRESTAPIを使用してSwagger2をセットアップできます。

3. APIの作成

まず、Products APIを作成し、生成されたドキュメントを確認します。

3.1. モデル

Productクラスを定義しましょう。

public class Product implements Serializable {
    private long id;
    private String name;
    private String price;

    // constructor and getter/setters
}

3.2. コントローラ

2つのAPIメソッドを定義しましょう。

@RestController
@ApiOperation("Products API")
public class ProductController {

    @PostMapping("/products")
    public ResponseEntity<Void> createProduct(@RequestBody Product product) {
        //creation logic
        return new ResponseEntity<>(HttpStatus.CREATED);
    }

    @GetMapping("/products/{id}")
    public ResponseEntity<Product> getProduct(@PathVariable Long id) {
        //retrieval logic
        return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
    }
}

プロジェクトを実行すると、ライブラリは公開されているすべてのパスを読み取り、それらに対応するドキュメントを作成します。

デフォルトのURLhttp：// localhost：8080 / swagger-ui /index.htmlでドキュメントを表示してみましょう。

コントローラメソッドをさらに拡張して、それぞれのドキュメントを確認できます。次に、それらについて詳しく見ていきます。

4. ドキュメントをわかりやすくする

それでは、メソッドのさまざまな部分に説明を追加して、ドキュメントをよりわかりやすくしましょう。

4.1. メソッドとパラメーターに説明を追加

メソッドを記述的にするためのいくつかの方法を見てみましょう。メソッド、パラメーター、および応答コードに説明を追加します。 getProduct（）メソッドから始めましょう。

@ApiOperation(value = "Get a product by id", notes = "Returns a product as per the id")
@ApiResponses(value = {
  @ApiResponse(code = 200, message = "Successfully retrieved"),
  @ApiResponse(code = 404, message = "Not found - The product was not found")
})
@GetMapping("/products/{id}")
public ResponseEntity<Product> getProduct(@PathVariable("id") @ApiParam(name = "id", value = "Product id", example = "1") Long id) {
    //retrieval logic
    return ResponseEntity.ok(new Product(1, "Product 1", "$21.99"));
}

@ApiOperation は、APIメソッドのプロパティを定義します。 value プロパティを使用して操作に名前を追加し、 notes[ X183X]プロパティ。

@ ApiResponses は、応答コードに付随するデフォルトのメッセージを上書きするために使用されます。変更する応答メッセージごとに、を追加する必要があります @ApiResponse 物体。

たとえば、製品が見つからず、このシナリオでAPIがHTTP404ステータスを返すとします。カスタムメッセージを追加しないと、元のメッセージ「見つかりません」がわかりにくくなる可能性があります。発信者は、URLが間違っていると解釈する可能性があります。ただし、「製品が見つかりませんでした」という説明を追加すると、より明確になります。

@ApiParam メソッドパラメーターのプロパティを定義します。パス、クエリ、ヘッダー、およびフォームパラメーターと一緒に使用できます。「id」パラメーターの名前、値（説明）、および例を追加しました。カスタマイズを追加しなかった場合、最初の画像に示されているように、ライブラリはパラメーターの名前とタイプのみを取得します。

これによりドキュメントがどのように変更されるかを見てみましょう。

ここでは、APIパス / products /{id}の横に「Getaproductid」という名前が表示されています。そのすぐ下にも説明があります。さらに、[パラメータ]セクションには、フィールドidの説明と例があります。そして最後に、[応答]セクションで、200コードと404コードのエラーの説明がどのように変更されたかを確認できます。

4.2. モデルに説明と例を追加する

createProduct（）メソッドでも同様の改善を行うことができます。さらに、このメソッドは Product オブジェクトを受け入れるため、Productクラス自体に説明と例を提供する方が理にかなっています。

これを実現するために、Productクラスにいくつかの変更を加えましょう。

@ApiModelProperty(notes = "Product ID", example = "1", required = true) 
private Long id; 
@ApiModelProperty(notes = "Product name", example = "Product 1", required = false) 
private String name; 
@ApiModelProperty(notes = "Product price", example = "$100.00", required = true) 
private String price;

@ApiModelPropertyアノテーションは、フィールドのプロパティを定義します。各フィールドでこのアノテーションを使用して、ノート（説明）、例、およびを設定しました。 requiredプロパティ。

アプリケーションを再起動して、製品モデルのドキュメントをもう一度見てみましょう。

これを元のドキュメント画像と比較すると、新しい画像には、必要なパラメータを識別するための例、説明、および赤いアスタリスク（*）が含まれていることがわかります。

モデルに例を追加することで、モデルを入力または出力として使用するすべてのメソッドでサンプル応答を自動的に作成できます。たとえば、 getProduct（）メソッドに対応する画像から、応答には、モデルで提供したものと同じ値を含む例が含まれていることがわかります。

ドキュメントに例を追加すると、値の形式がさらに正確になるため、重要です。モデルに日付、時刻、価格などのフィールドが含まれている場合は、正確な値の形式が必要です。事前にフォーマットを定義しておくと、APIプロバイダーとAPIクライアントの両方にとって開発プロセスがより効果的になります。

5. 結論

この記事では、APIドキュメントの読みやすさを向上させるさまざまな方法について説明しました。アノテーション@ApiParam、@ ApiOperation、@ ApiResponses、@ ApiResponse、および@ApiModelProperty を使用して、メソッド、パラメーター、エラーメッセージ、およびモデルを文書化する方法を学習しました。

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

getdocs

13036