SwaggerAPI応答でオブジェクトのリストを設定する

投稿日: 2022-10-27 2022-10-27
タグ: OpenAPI, REST, Swagger

1. 概要

このチュートリアルでは、SwaggerAPIレスポンスを変更する方法を学習します。まず、OpenAPI仕様とSwaggerAPI応答の説明から始めます。次に、Spring Boot を使用して簡単な例を実装し、OpenApi3.0を使用してspringREST APIを文書化します。その後、Swaggerのアノテーションを使用して、応答本文を設定し、オブジェクト。

2. 実装

この実装では、SwaggerUIを使用して単純なSpring Bootプロジェクトをセットアップします。その結果、アプリケーションのすべてのエンドポイントを含むSwaggerUIが作成されます。その後、応答本文を変更してリストを返します。

2.1. SwaggerUIを使用したSpringBootプロジェクトのセットアップ

まず、製品のリストを保存するProductServiceクラスを作成します。次に、 ProductController、でREST APIを定義して、ユーザーが作成された製品のリストを取得できるようにします。

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

public class Product {
    String code;
    String name;

<span style="font-weight: 400">    // standard getters and setters</span>
}

次に、ProductServiceクラスを実装します。

@Service
public class ProductService {
    List<Product> productsList = new ArrayList<>();

    public List<Product> getProductsList() {
        return productsList;
    }
}

最後に、RESTAPIを定義するためのControllerクラスがあります。

@RestController
public class ProductController {
    final ProductService productService;

    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    @GetMapping("/products")
    public List<Product> getProductsList(){
        return productService.getProductsList();
    }
}

2.2. SwaggerAPI応答の変更

RESTAPIを文書化するために利用できるSwaggerアノテーションがいくつかあります。 @ApiResponsesを使用して、@ ApiResponseの配列を定義し、RESTAPIの予想される応答を定義できます。

次に、@ ApiResponsesを使用して、応答コンテンツをgetProductListメソッドのProductオブジェクトのリストに設定しましょう。

@ApiResponses(
  value = {
    @ApiResponse(
      content = {
        @Content(
          mediaType = "application/json",
          array = @ArraySchema(schema = @Schema(implementation = Product.class)))
      })
  })
@GetMapping("/products")
public List<Product> getProductsList() {
    return productService.getProductsList();
}

この例では、応答本文でメディアタイプを application /jsonに設定します。さらに、contentキーワードを使用して応答本文を変更しました。また、 array キーワードを使用して、Productオブジェクトの配列に応答を設定します。

3. 結論

このチュートリアルでは、OpenAPI仕様とSwaggerAPI応答について簡単に説明しました。 Swaggerは、さまざまなキーワードを含む@ApiResponsesなどのさまざまな注釈を提供します。したがって、これらを簡単に使用して、アプリケーションの要件を満たすように要求と応答を変更できます。この実装では、 @ApiResponses を使用して、Swagger応答本文のコンテンツを変更しました。

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

getdocs

13036