REST API の作成

このガイドでは、Spring で "Hello, World" RESTful Web サービスを作成するプロセスを説明します。画面を使用した "Hello, World" は Thymeleaf Web 画面の作成を参照してください。

構築するもの

http://localhost:8080/greeting で HTTP GET リクエストを受け入れるサービスを構築します。

次のように、挨拶の JSON 表現で応答します。

{"id":1,"content":"Hello, World!"}

次のように、クエリ文字列のオプションの name パラメーターを使用して、グリーティングをカスタマイズできます。

http://localhost:8080/greeting?name=User

name パラメーター値は、次のように、World のデフォルト値をオーバーライドし、レスポンスに反映されます。

{"id":1,"content":"Hello, User!"}

必要なもの

約 15 分
Eclipse STS や IntelliJ IDEA のような任意の IDE または VSCode のようなテキストエディター
Java 17 以降
Gradle 7.5+ (英語) または Maven 3.5+ [Apache] (英語)
コードを直接 IDE にインポートすることもできます。

本ガイドの完成までの流れ

ほとんどの Spring 入門ガイドと同様に、最初から始めて各ステップを完了するか、すでに慣れている場合は基本的なセットアップステップをバイパスできます。いずれにしても、最終的に動作するコードになります。

最初から始めるには、Spring Initializr から開始に進みます。

基本をスキップするには、次の手順を実行します。

このガイドを Eclipse で「Spring 入門コンテンツのインポート」するか、ソースリポジトリをダウンロードして解凍、または、Git (英語) を使用してクローンを作成します。git clone https://github.com/spring-guides/gs-rest-service.git
gs-rest-service/initial に cd
リソース表現クラスを作成するにジャンプしてください。

完了したときは、gs-rest-service/complete のコードに対して結果を確認できます。

Spring Initializr から開始

IDE を使用する場合はプロジェクト作成ウィザードを使用します。IDE を使用せずにコマンドラインなどで開発する場合は、この事前に初期化されたプロジェクトからプロジェクトを ZIP ファイルとしてダウンロードできます。このプロジェクトは、このチュートリアルの例に合うように構成されています。

プロジェクトを手動で初期化するには:

IDE のメニューまたはブラウザーから Spring Initializr を開きます。アプリケーションに必要なすべての依存関係を取り込み、ほとんどのセットアップを行います。
Gradle または Maven のいずれかと、使用する言語を選択します。このガイドは、Java を選択したことを前提としています。
依存関係をクリックして、Spring Web を選択します。
生成をクリックします。
結果の ZIP ファイルをダウンロードします。これは、選択して構成された Web アプリケーションのアーカイブです。

Eclipse や IntelliJ のような IDE は新規プロジェクト作成ウィザードから Spring Initializr の機能が使用できるため、手動での ZIP ファイルのダウンロードやインポートは不要です。

プロジェクトを Github からフォークして、IDE または他のエディターで開くこともできます。

リソース表現クラスを作成する

プロジェクトとビルドシステムをセットアップしたため、Web サービスを作成できます。

サービスの相互作用について考えることでプロセスを開始します。

サービスは、/greeting の GET リクエストを処理します。オプションで、クエリ文字列に name パラメーターを使用します。GET リクエストは、挨拶を表す本文に JSON を含む 200 OK レスポンスを返す必要があります。次の出力のようになります。

{
    "id": 1,
    "content": "Hello, World!"
}

id フィールドは挨拶の一意の識別子であり、content は挨拶のテキスト表現です。

挨拶表現をモデル化するには、リソース表現クラスを作成します。これを行うには、次のリスト ( src/main/java/com/example/restservice/Greeting.java から) が示すように、id および content データの Java レコードクラスを提供します。

package com.example.restservice;

public record Greeting(long id, String content) { }

このアプリケーションは、Jackson JSON [GitHub] (英語) ライブラリを使用して、型 Greeting のインスタンスを JSON に自動的にマーシャリングします。Jackson は、Web スターターによってデフォルトで含まれています。

リソースコントローラーを作成する

RESTful Web サービスを構築する Spring のアプローチでは、HTTP リクエストはコントローラーによって処理されます。これらのコンポーネントは @RestController (Javadoc) アノテーションによって識別され、次のリスト（src/main/java/com/example/restservice/GreetingController.java から）に示されている GreetingController は、Greeting クラスの新しいインスタンスを返すことにより、/greeting に対する GET リクエストを処理します。

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/greeting")
	public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}

このコントローラーは簡潔でシンプルですが、内部ではさまざまなことが行われています。段階的にそれを分解します。

@GetMapping アノテーションは、/greeting への HTTP GET リクエストが greeting() メソッドにマップされることを保証します。

他の HTTP 動詞のコンパニオンアノテーションがあります（POST の場合は @PostMapping など）。また、@RequestMapping アノテーションもあり、それらはすべて派生しており、シノニムとして機能します（例: @RequestMapping(method=GET)）。

@RequestParam は、クエリ文字列パラメーター name の値を greeting() メソッドの name パラメーターにバインドします。name パラメーターがリクエストにない場合、World の defaultValue が使用されます。

メソッド本体の実装は、counter の次の値に基づいて id および content 属性を持つ新しい Greeting オブジェクトを作成して返し、挨拶 template を使用して指定された name をフォーマットします。

従来の MVC コントローラーと前述の RESTful Web サービスコントローラーの主な違いは、HTTP レスポンスの本文が作成される方法です。この RESTful Web サービスコントローラーは、ビューテクノロジーに依存して、グリーティングデータを HTML にサーバー側でレンダリングするのではなく、Greeting オブジェクトを生成して返します。オブジェクトデータは、JSON として HTTP レスポンスに直接書き込まれます。

このコードは Spring @RestController (Javadoc) アノテーションを使用します。これは、すべてのメソッドがビューではなくドメインオブジェクトを返すコントローラーとしてクラスをマークします。@Controller と @ResponseBody の両方を含めるための略記です。

Greeting オブジェクトは JSON に変換する必要があります。Spring の HTTP メッセージコンバーターのサポートにより、この変換を手動で行う必要はありません。Jackson 2 [GitHub] (英語) はクラスパス上にあるため、Spring の MappingJackson2HttpMessageConverter (Javadoc) が自動的に選択され、Greeting インスタンスが JSON に変換されます。

サービスを実行する

Spring Initializr はアプリケーションクラスを作成します。この場合、クラスをさらに変更する必要はありません。次のリスト (src/main/java/com/example/restservice/RestServiceApplication.java から) は、アプリケーションクラスを示しています。

package com.example.restservice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class RestServiceApplication {

	public static void main(String[] args) {
		SpringApplication.run(RestServiceApplication.class, args);
	}

}

@SpringBootApplication は、次のすべてを追加する便利なアノテーションです。

@Configuration: アプリケーションコンテキストの Bean 定義のソースとしてクラスにタグを付けます。
@EnableAutoConfiguration: クラスパス設定、他の Bean、さまざまなプロパティ設定に基づいて Bean の追加を開始するよう Spring Boot に指示します。例: spring-webmvc がクラスパスにある場合、このアノテーションはアプリケーションに Web アプリケーションとしてフラグを立て、DispatcherServlet のセットアップなどの主要な動作をアクティブにします。
@ComponentScan: Spring に、com/example パッケージ内の他のコンポーネント、構成、サービスを探して、コントローラーを検出させるように指示します。

main() メソッドは、Spring Boot の SpringApplication.run() メソッドを使用してアプリケーションを起動します。XML が 1 行もないことに気付きましたか？ web.xml ファイルもありません。この Web アプリケーションは 100% 純粋な Java であり、接続機能やインフラストラクチャの構成に対処する必要はありませんでした。

実行可能 JAR を構築する

コマンドラインから Gradle または Maven を使用してアプリケーションを実行できます。必要なすべての依存関係、クラス、リソースを含む単一の実行可能 JAR ファイルを構築して実行することもできます。実行可能な jar を構築すると、開発ライフサイクル全体、さまざまな環境などで、アプリケーションとしてサービスを簡単に提供、バージョン管理、デプロイできます。

Gradle を使用する場合、./gradlew bootRun を使用してアプリケーションを実行できます。または、次のように、./gradlew build を使用して JAR ファイルをビルドしてから、JAR ファイルを実行できます。

java -jar build/libs/gs-rest-service-0.1.0.jar

Maven を使用する場合、./mvnw spring-boot:run を使用してアプリケーションを実行できます。または、次のように、./mvnw clean package で JAR ファイルをビルドしてから、JAR ファイルを実行できます。

java -jar target/gs-rest-service-0.1.0.jar

ここで説明する手順は、実行可能な JAR を作成します。クラシック WAR ファイルを作成することもできます。

ロギング出力が表示されます。サービスは数秒以内に起動して実行されるはずです。

サービスをテストする

サービスが起動したため、http://localhost:8080/greeting にアクセスしてください:

{"id":1,"content":"Hello, World!"}

http://localhost:8080/greeting?name=User にアクセスして、name クエリ文字列パラメーターを提供します。次のように、content 属性の値が Hello, World! から Hello, User! に変化することに注意してください。

{"id":2,"content":"Hello, User!"}

この変更は、GreetingController の @RequestParam 配置が期待どおりに機能していることを示しています。name パラメーターには World のデフォルト値が指定されていますが、クエリ文字列を介して明示的にオーバーライドできます。

id 属性が 1 から 2 に変更されたことにも注意してください。これは、複数のリクエストにわたって同じ GreetingController インスタンスに対して作業していることと、その counter フィールドが期待どおりに各呼び出しで増加していることを証明しています。

要約

おめでとう！ Spring を使用して RESTful Web サービスを開発しました。

コードを入手する

リポジトリに移動

FREE

クラウドでの作業

Spring アカデミーのクラウドでガイドを完成させよう。

Spring アカデミーへ

プロジェクト

Spring Boot