カテゴリ: Spring 更新日: 2026/11/06

JavaのSpring Bootでの@ResponseEntityアノテーションの使い方を初心者向けに徹底解説!

Springの@ResponseEntityアノテーション
Springの@ResponseEntityアノテーション

先生と生徒の会話形式で理解しよう

生徒

「Spring BootでHTTPレスポンスをカスタマイズしたいんですが、どうすればいいですか?」

先生

「HTTPレスポンスをカスタマイズする場合は、@ResponseEntityアノテーションが便利です。これを使うと、ステータスコードやヘッダーも自由に設定できます。」

生徒

「具体的にどう使うんですか?」

先生

「基本的な使い方から見ていきましょう!」

1. @ResponseEntityとは?

1. @ResponseEntityとは?
1. @ResponseEntityとは?

JavaのSpring Bootフレームワークでは、@ResponseEntityアノテーションを使うことで、サーバーからクライアントに返すHTTPレスポンスの中身を細かくコントロールできます。通常のコントローラーメソッドは、メソッドの戻り値をそのままレスポンスボディとして返し、ステータスコードは自動的に「200 OK」になりますが、@ResponseEntityを使うと、ステータスコード、レスポンスボディ、ヘッダーを自分の意図どおりに設定できます。

もう少しかみ砕いて言うと、@ResponseEntityは「どんな結果を、どんな状態で返すか」をひとまとめにして表現するための入れ物のようなものです。例えば「処理が成功したからメッセージを返したい」「エラーが起きたのでエラーメッセージとエラー用のステータスコードを返したい」といったときに、この入れ物の中に「文字列やオブジェクト」「ステータスコード」「必要ならヘッダー情報」を詰め込んで返すイメージです。

初心者のうちは、まず「ResponseEntity<型>という形で、どんなデータを返すかを指定する」「第2引数にHttpStatus.OKなどのステータスコードを渡せる」という二つを覚えておくと理解しやすくなります。これが分かってくると、Spring BootでREST APIを作るときに、「成功」「失敗」「データなし」といった状態をきちんとHTTPレスポンスとして表現できるようになり、実践的なWebアプリケーション開発に一歩近づけます。

2. @ResponseEntityの基本的な使い方

2. @ResponseEntityの基本的な使い方
2. @ResponseEntityの基本的な使い方

ここでは、@ResponseEntityを実際にどう書くのか、いちばんシンプルな例で確認してみましょう。まずは「/hello」というパスにアクセスしたときに、メッセージとHTTPステータスコードをセットで返す基本パターンです。


import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ExampleController {

    @GetMapping("/hello")
    public ResponseEntity<String> sayHello() {
        return new ResponseEntity<>("Hello, World!", HttpStatus.OK);
    }
}

このコードでは、/helloというURLにブラウザからアクセスすると、「Hello, World!」という文字列と一緒にHTTPステータスコード200(OK)が返されます。ResponseEntity<String>という戻り値の型は、「文字列をボディとして持つHTTPレスポンスを返します」という意味だと考えると分かりやすいです。

new ResponseEntity<>("Hello, World!", HttpStatus.OK)の第1引数がクライアントに返すメッセージ(レスポンスボディ)、第2引数がステータスコードです。つまりこの1行だけで、「内容はこのテキスト」「結果は成功(OK)」という情報をまとめて返していることになります。ブラウザの開発者ツールでネットワークタブを開いてみると、ステータスが「200 OK」になっていることも確認できるので、Spring BootとHTTPレスポンスの関係を体感しながら学ぶことができます。

3. HTTPステータスコードの設定

3. HTTPステータスコードの設定
3. HTTPステータスコードの設定

@ResponseEntityでは、HTTPステータスコードを自分で指定することができます。HTTPステータスコードとは、「リクエストの結果がどうなったか」を数字で表したものです。例えば、うまくいったときの200 OK、入力が間違っているときの400 Bad Request、ページが見つからないときの404 Not Foundといった種類があります。

まずは、リクエストが正しくない場合に「400 Bad Request」を返す、とてもシンプルなサンプルを見てみましょう。


@GetMapping("/error")
public ResponseEntity<String> handleError() {
    return new ResponseEntity<>("Bad Request", HttpStatus.BAD_REQUEST);
}

このメソッドに対応する/errorというURLにアクセスすると、レスポンスボディには「Bad Request」という文字列が入り、ステータスコードにはHttpStatus.BAD_REQUEST(数値としては400)が設定されます。ブラウザやAPIクライアントの画面では、メッセージだけでなく「400 Bad Request」という結果も確認できるので、「入力が間違っている」「リクエストが不正」ということを機械にも人にも分かる形で伝えられます。

同じような書き方で、成功時に200 OKを返したり、新しくデータを作成したときに201 CREATEDを返したりすることもできます。Spring BootのコントローラーでResponseEntity<String>を使うと、「どんなメッセージを返すか」と同時に「その結果をどう評価するか(成功なのか、エラーなのか)」をHTTPステータスコードとして表現できるようになり、REST APIらしい分かりやすいWebアプリケーションを作りやすくなります。

4. レスポンスヘッダーのカスタマイズ

4. レスポンスヘッダーのカスタマイズ
4. レスポンスヘッダーのカスタマイズ

HTTPレスポンスには「ヘッダー」と呼ばれる追加情報を載せることができます。ヘッダーは、荷物に貼る送り状のようなもので、「このデータはどんな形式か」「どこから来たデータか」など、ブラウザやクライアント側に伝えたいメタデータを記載する場所だと考えるとイメージしやすいです。

Spring Bootでは、HttpHeadersクラスを使うことで、このレスポンスヘッダーを簡単にカスタマイズできます。まずは、独自のヘッダーを1つ追加する、シンプルな例を見てみましょう。


import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HeaderController {

    @GetMapping("/custom-header")
    public ResponseEntity<String> customHeader() {
        HttpHeaders headers = new HttpHeaders();
        headers.add("Custom-Header", "MyValue");
        return new ResponseEntity<>("Header added!", headers, HttpStatus.OK);
    }
}

このコードでは、/custom-headerにアクセスすると、レスポンスボディとして「Header added!」という文字列が返されるだけでなく、レスポンスヘッダーにCustom-Header: MyValueという独自の情報が1行追加されます。ブラウザの開発者ツールやAPIクライアントのレスポンスヘッダーの一覧を確認すると、この項目が増えているのが分かります。

ポイントは、HttpHeaders headers = new HttpHeaders();でヘッダー用のオブジェクトを用意し、headers.add("名前", "値")で好きなヘッダーを登録してから、new ResponseEntity<>(ボディ, headers, ステータス)の形でまとめて返しているところです。Spring Bootのコントローラーでレスポンスヘッダーを扱えるようになると、「ダウンロード用のレスポンスにファイル名を付ける」「認証用のトークンをヘッダーに載せる」といった実践的なWeb APIの実装にもスムーズにつなげられるようになります。

5. ボディの内容をカスタマイズする方法

5. ボディの内容をカスタマイズする方法
5. ボディの内容をカスタマイズする方法

@ResponseEntityは、単純な文字列だけでなく、Javaのオブジェクトそのものをレスポンスボディとして返すことができます。実際のWebアプリケーションやREST APIでは、文字列よりも「ユーザー情報」「商品情報」のようなまとまったデータを返すことが多いので、この仕組みを押さえておくと一気に実践寄りのSpring Boot開発に近づきます。

たとえば、ユーザーの名前と年齢をまとめて返したい場合は、次のように専用のクラスを用意して、それをResponseEntityで返すだけです。


import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    public static class User {
        private String name;
        private int age;

        // コンストラクタ
        public User(String name, int age) {
            this.name = name;
            this.age = age;
        }

        // ゲッター
        public String getName() { return name; }
        public int getAge() { return age; }
    }

    @GetMapping("/user")
    public ResponseEntity<User> getUser() {
        User user = new User("John", 30);
        return new ResponseEntity<>(user, HttpStatus.OK);
    }
}

このコードでは、/userエンドポイントにアクセスすると、Userクラスのインスタンスがレスポンスボディとして返されます。Spring Bootは内部でこのオブジェクトをJSON形式に自動変換してくれるため、開発者は「Userオブジェクトを返す」ことだけに集中すれば大丈夫です。特別な設定をしなくても、ゲッターメソッド(getNameやgetAge)が定義されていれば、そのプロパティがJSONの項目として出力されます。

実際にブラウザやAPIクライアントから/userにアクセスすると、次のようなJSONデータが返ってきます。Javaのオブジェクトが、そのまま「キーと値」の形に変換されているのが分かります。


{
    "name": "John",
    "age": 30
}

このように、ResponseEntity<User>のような形で型を指定しておけば、「どんなデータを返すAPIなのか」がメソッドシグネチャから一目で分かるようになります。複数の項目をまとめて返したいときや、ユーザー情報・商品情報・注文情報などを扱うときは、それぞれ専用のクラスを作り、@ResponseEntityで返すスタイルを覚えておくと、Spring BootのREST API設計がぐっとスムーズになります。

6. エラーハンドリングと@ResponseEntity

6. エラーハンドリングと@ResponseEntity
6. エラーハンドリングと@ResponseEntity

@ResponseEntityは成功時だけでなく、エラーを分かりやすく返す場面でも大きく役立ちます。WebアプリやREST APIでは「データが存在しない」「入力が間違っている」といった状況が必ず発生するため、初心者のうちからエラーレスポンスの返し方を押さえておくことが大切です。

まずは、もっともよく使う「リソースが見つからない場合」に404 Not Foundを返す基本的なサンプルから見てみましょう。


@GetMapping("/not-found")
public ResponseEntity<String> notFound() {
    // データが無い状況を想定したサンプル
    return new ResponseEntity<>("指定されたデータは見つかりませんでした", HttpStatus.NOT_FOUND);
}

このメソッドにアクセスすると、レスポンスボディには「指定されたデータは見つかりませんでした」というメッセージが返り、ステータスコードには404 Not Foundが設定されます。これによって「画面ではメッセージを確認でき、機械的にもエラーとして処理できる」という両方の利点を持つレスポンスになります。

プログラミング未経験の方は「エラーが起きたら、その理由をメッセージとして返し、HTTPステータスコードで状態を表す」と覚えると理解しやすくなります。こうした小さな工夫が、分かりやすく信頼性の高いWeb APIを作る第一歩につながります。

7. まとめ

7. まとめ
7. まとめ

今回の記事では、JavaのSpring Bootで使用する@ResponseEntityアノテーションについて学びました。@ResponseEntityを使用すると、HTTPレスポンスの内容を細かくカスタマイズできるため、APIの設計や開発においてとても便利です。特に、ステータスコードの設定やレスポンスヘッダーの追加、オブジェクトを返す際のシリアライズの処理など、幅広い用途に対応できます。

以下は、今回学んだ重要なポイントです。

  • @ResponseEntityを使うことで、HTTPステータスコードを自由に設定可能。
  • レスポンスヘッダーを追加して、カスタムデータを返すことができる。
  • オブジェクトを返す場合、自動的にJSON形式にシリアライズされる。
  • エラーハンドリングにも有効で、適切なステータスコードを返すことができる。

以下は、@ResponseEntityの様々な使い方をまとめたサンプルプログラムです。


import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class SummaryController {

    // ステータス200(OK)の例
    @GetMapping("/success")
    public ResponseEntity<String> successResponse() {
        return new ResponseEntity<>("Success!", HttpStatus.OK);
    }

    // カスタムヘッダーの追加
    @GetMapping("/header-example")
    public ResponseEntity<String> headerExample() {
        HttpHeaders headers = new HttpHeaders();
        headers.add("X-Example-Header", "HeaderValue");
        return new ResponseEntity<>("Header added", headers, HttpStatus.OK);
    }

    // ステータス404(Not Found)の例
    @GetMapping("/not-found-example")
    public ResponseEntity<String> notFoundExample() {
        return new ResponseEntity<>("Resource not found", HttpStatus.NOT_FOUND);
    }

    // JSONオブジェクトのレスポンス
    @GetMapping("/json-example")
    public ResponseEntity<User> jsonExample() {
        User user = new User("Alice", 25);
        return new ResponseEntity<>(user, HttpStatus.OK);
    }

    // エラーハンドリングの例
    @GetMapping("/bad-request-example")
    public ResponseEntity<String> badRequestExample() {
        return new ResponseEntity<>("Bad request error", HttpStatus.BAD_REQUEST);
    }
}

このコードには、ステータスコード、カスタムヘッダー、エラーハンドリング、JSONレスポンスの例が含まれています。実際の開発では、これらを組み合わせてAPIの挙動をカスタマイズすることが一般的です。

先生と生徒の振り返り会話

生徒

「@ResponseEntityを使うと、HTTPレスポンスをかなり細かく制御できるんですね。」

先生

「そうですね。特に、APIの開発ではレスポンスの内容を調整することが大切なので、@ResponseEntityは非常に役立ちます。」

生徒

「エラーハンドリングも簡単にできるので、クライアントにわかりやすいエラーメッセージを返すことができますね。」

先生

「その通りです。適切なステータスコードとメッセージを返すことで、クライアント側の開発者もデバッグしやすくなります。」

生徒

「これで、Spring BootのAPI開発がもっとスムーズにできそうです!」

先生

「ぜひ試してみてください。実際に使いながら学ぶと理解が深まりますよ。」

この記事を読んだ人からの質問

この記事を読んだ人からの質問
この記事を読んだ人からの質問

プログラミング初心者からのよくある疑問/質問を解決します

@ResponseEntityを使うと何ができますか?

@ResponseEntityを使うと、HTTPレスポンスのステータスコード、ヘッダー、ボディを細かく設定できます。これにより、APIのレスポンスをクライアントの要求に合わせて柔軟にカスタマイズできます。

@ResponseEntityと通常のコントローラーのレスポンスの違いは何ですか?

通常のコントローラーはデフォルトでHTTPステータス200(OK)を返しますが、@ResponseEntityを使うと、ステータスコードやヘッダーをカスタマイズできる点が大きな違いです。

ステータスコードを設定する方法を教えてください。

@ResponseEntityの第2引数にHttpStatusを指定することで、ステータスコードを設定できます。例えば、HttpStatus.OKやHttpStatus.BAD_REQUESTなどを使用します。

レスポンスヘッダーを追加するにはどうすればいいですか?

HttpHeadersクラスを使ってヘッダーを作成し、それを@ResponseEntityの引数に渡すことでレスポンスヘッダーを追加できます。

JSON形式でデータを返すにはどうしたらいいですか?

@ResponseEntityでオブジェクトを返すと、Spring Bootが自動的にそのオブジェクトをJSON形式にシリアライズしてレスポンスを生成します。

エラーが発生した場合、クライアントに適切なエラーメッセージを返す方法は?

@ResponseEntityを使って、エラーメッセージとHTTPステータスコード(例えばHttpStatus.NOT_FOUNDやHttpStatus.BAD_REQUEST)を設定することで、クライアントに適切なエラーメッセージを返せます。

@ResponseEntityを使うとパフォーマンスに影響はありますか?

@ResponseEntity自体が軽量なため、通常のレスポンスに比べて大きなパフォーマンス差はありません。ただし、複雑な処理を追加するとパフォーマンスに影響する可能性があります。

Spring Bootで@ResponseEntityを使うのはどのような場面が適していますか?

カスタムレスポンスが必要な場合や、エラーメッセージを詳細に設定する必要がある場合、またクライアントと明確な通信を行いたい場合に適しています。

@ResponseEntityを使うとき、オブジェクトの中にネストされたデータもJSONとして返せますか?

はい、Spring Bootはオブジェクト内のネストされたデータも自動的にシリアライズしてJSONとして返すことができます。

HTTPステータスコードの設定やヘッダーの追加を行う代わりに、通常の方法で対応することはできますか?

通常の方法でも可能ですが、コードが煩雑になりやすいため、@ResponseEntityを使う方がシンプルかつ管理しやすい設計になります。
生成AIを基礎から学びたい方へ

ChatGPTなどの生成AIをこれから学びたい方に向けて、AIスキルアカデミーの口コミ・評判、料金、無料セミナーの内容を詳しくまとめています。

AIスキルアカデミーの口コミ・評判を詳しく見る
関連記事:
カテゴリの一覧へ
新着記事
New1
Spring
Spring Data JPAのJpaRepositoryインターフェースの使い方を完全ガイド!初心者でも安心
更新記事
New2
Java
JavaのVectorクラスの使い方を完全ガイド!初心者でもわかるコレクションの基本
更新記事
New3
JSP
JSPのEL式で論理演算を行う方法を完全解説 初心者でもわかるAND OR NOTの使い方と条件分岐
新規投稿
New4
Java
JavaのHashMapクラスを完全ガイド!初心者でもわかる連想配列の使い方
更新記事
人気記事
No.1
Java&Spring記事人気No1
Servlet
JavaのGenericServletクラスの使い方を徹底解説!初心者でもわかるServletの基本とHttpServletとの違い
No.2
Java&Spring記事人気No2
Servlet
JavaのHttpServletRequestWrapperとauthenticateメソッドとは?初心者にもわかりやすく解説!
No.3
Java&Spring記事人気No3
Servlet
JavaのHttpServletRequestWrapperとlogoutメソッドを完全ガイド!初心者でもわかるログアウト処理の方法
No.4
Java&Spring記事人気No4
Servlet
JavaのHttpServletRequestWrapperとgetMethodメソッドの使い方を徹底解説!初心者向けHTTPリクエストメソッド取得ガイド
No.5
Java&Spring記事人気No5
Servlet
JavaのHttpServletRequestWrapperとgetUserPrincipalメソッドを徹底解説!初心者でもわかる認証ユーザー情報の取得方法
No.6
Java&Spring記事人気No6
Servlet
JavaのHttpServletRequestWrapperとupgradeメソッドを徹底解説!初心者でもわかるプロトコルアップグレードの基本
No.7
Java&Spring記事人気No7
Java
Java Streamのgenerateメソッド完全ガイド!初心者でもわかる乱数と定数ストリーム生成
No.8
Java&Spring記事人気No8
Servlet
JavaのサーブレットのdoGetメソッドとは?GETリクエストの仕組みと使い方を初心者向けに徹底解説