この記事でわかること
JSONの指定で型を取り違えた3つの失敗を再現し、注釈はString定数、ResponseEntityの応答APIはMediaTypeを受け取ることから修正を判断します。コンパイル成功とJSON応答を別々に確認します。
MediaType.APPLICATION_JSONをproducesへ入れると型が合わず、APPLICATION_JSON_VALUEをResponseEntityのcontentTypeへ渡しても型が合わない。どちらもJSONの指定に見えますが、受け取るAPIが要求する型が違います。注釈のconsumes・producesにはString定数、ResponseEntity.BodyBuilder.contentTypeとHttpHeaders.setContentTypeにはMediaTypeを渡します。
この記事では、注文内容をJSONで返すプレビューAPIを例に、3つのコンパイル失敗を再現して修正します。架空の小さなAPIで、受け取った商品コードと個数を返すだけです。注文の保存、料金計算、在庫の確保は行いません。
注釈にはString定数、型付きの応答APIにはMediaTypeを渡す
最初に、どこを直すかを決めます。APPLICATION_JSON_VALUEは"application/json"というString定数で、APPLICATION_JSONはMediaType型のオブジェクトです。名前に_VALUEが付く方が上位版・新しい版という関係ではありません。
| 使う場所・受け側 | 要求する型 | 今回の指定 |
|---|---|---|
@PostMappingのconsumes・produces | String[] | MediaType.APPLICATION_JSON_VALUE |
@GetMappingのproduces | String[] | MediaType.APPLICATION_JSON_VALUE |
ResponseEntity.BodyBuilder.contentType | MediaType | MediaType.APPLICATION_JSON |
HttpHeaders.setContentType | MediaType | MediaType.APPLICATION_JSON |
IDEで同じような名前の候補が並んでも、「JSONだからこれ」と選ばず、エラーになった呼出しの受け側を開きます。今回ならResponseEntity.BodyBuilderのcontentType(MediaType)まで確認します。クラス名と引数型を組み合わせて読むと、定数名を暗記するより他のAPIにも応用できます。
@PostMapping・@GetMappingで指定する形式も、元の@RequestMappingではString配列の属性です。1個だけなら配列の波括弧を省略してString定数を渡せます。配列だからMediaTypeをそのまま入れられる、という意味ではありません。
3つの失敗例は通常のビルドから分離して再現する
ZIPのexamples/brokenに、わざとコンパイルが通らない3ファイルを入れています。これらはsrc/main/javaやsrc/test/javaの下に置かず、通常のアプリのビルド対象から外しました。テストがJDKのJavaCompilerを呼び出し、故障版は失敗、対応するexamples/fixedは成功することを確認します。
テスト全体が成功するのは、故障版もビルドできたという意味ではありません。「失敗させたい箇所が、期待した診断コード1件で失敗した」ことを含めて成功です。次の診断はJava17.0.8で実測したもので、IDEや言語設定によって文言は異なる場合があります。
producesへAPPLICATION_JSONを渡すとStringの型に合わない
次がAnnotationObject.javaの故障版全文です。producesの受け側はStringですが、右辺はMediaType型です。
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
class AnnotationObject {
@GetMapping(path = "/preview", produces = MediaType.APPLICATION_JSON)
String preview() { return "{}"; }
}実測した診断は、org.springframework.http.MediaTypeをjava.lang.Stringに変換できませんという内容でした。修正版は定数名をAPPLICATION_JSON_VALUEへ替えています。応答本文の"{}"やパスを変える必要はありません。
AnnotationObject.javaの全文を見る
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
class AnnotationObject {
@GetMapping(path = "/preview", produces = MediaType.APPLICATION_JSON_VALUE)
String preview() { return "{}"; }
}ResponseEntity.contentTypeへ_VALUEを渡すとMediaTypeの型に合わない
こちらのBuilderString.javaは逆です。ResponseEntity.ok()が返すBodyBuilderのcontentTypeは、文字列ではなくMediaTypeを受け取ります。
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
class BuilderString {
ResponseEntity<String> preview() {
return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON_VALUE).body("{}");
}
}診断は、java.lang.Stringをorg.springframework.http.MediaTypeに変換できませんという内容です。この場合は_VALUEを外したAPPLICATION_JSONを渡します。注釈で選んだ定数を、応答を作るAPIへ機械的にコピーしないようにします。
BuilderString.javaの全文を見る
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
class BuilderString {
ResponseEntity<String> preview() {
return ResponseEntity.ok().contentType(MediaType.APPLICATION_JSON).body("{}");
}
}注釈の中でtoStringを呼んでも定数式にならない
最初の失敗を見て、オブジェクトを文字列にすればよいと考えることがあります。しかし、次のAnnotationToString.javaも通りません。
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
class AnnotationToString {
@GetMapping(path = "/preview", produces = MediaType.APPLICATION_JSON.toString())
String preview() { return "{}"; }
}この診断は式が注釈の値として許可されませんでした。toString()の結果がStringであることと、注釈に使える定数式であることは別です。Javaの注釈では、String型の要素値に定数式という条件があります。実行時のメソッド呼出しで文字列を作る方法にはせず、最初からString定数であるAPPLICATION_JSON_VALUEを使います。
AnnotationToString.javaの全文を見る
import org.springframework.http.MediaType;
import org.springframework.web.bind.annotation.GetMapping;
class AnnotationToString {
@GetMapping(path = "/preview", produces = MediaType.APPLICATION_JSON_VALUE)
String preview() { return "{}"; }
}COMPILER AnnotationObject line=5 column=56 code=compiler.err.prob.found.req message=不適合な型: org.springframework.http.MediaTypeをjava.lang.Stringに変換できません:
FIXED AnnotationObject compiled=true
COMPILER BuilderString line=6 column=57 code=compiler.err.prob.found.req message=不適合な型: java.lang.Stringをorg.springframework.http.MediaTypeに変換できません:
FIXED BuilderString compiled=true
COMPILER AnnotationToString line=5 column=82 code=compiler.err.expression.not.allowable.as.annotation.value message=式が注釈の値として許可されません
FIXED AnnotationToString compiled=trueコンパイル前の型の問題とHTTPの形式の問題を分ける
ここまでの3件は、アプリを起動してリクエストを送る前の問題です。コンパイラが受け側と渡す値の型・注釈値の条件を照合して止めています。HTTP415や406が返ったという問題ではなく、Acceptヘッダーを変えてもコンパイル失敗は直りません。
一方、正しい型を渡してビルドが通っても、クライアントが送る形式とAPIの契約が合うかは別に確認します。consumesは受ける本文のContent-Type、producesは返せる形式とAcceptを照合する条件です。この違いと405・415・406の追試は既存記事へ分担します。
このページでは、定数の選択を修正して、JSON応答のヘッダーと本文を確認するところまでを扱います。メディアタイプを指定したこと自体が、任意のオブジェクトをJSONへ変換する仕組みではありません。今回のWeb Starterに含まれる変換器と、返す本文のJava型によってJSONを生成します。
修正版の注文プレビューでは注釈とResponseEntityを分けて指定する
実行するアプリのOrderPreviewController.java全文です。POSTのconsumes・producesは_VALUE、応答を組み立てるcontentTypeはMediaTypeを使っています。受信した商品コードと個数をプレビューとして返すだけで、DBへ登録しません。
package info.syachiku.mediatype;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class OrderPreviewController {
public record PreviewRequest(String itemCode, int quantity) {}
public record Preview(String itemCode, int quantity, String status) {}
@PostMapping(path = "/order-previews",
consumes = MediaType.APPLICATION_JSON_VALUE,
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<Preview> preview(@RequestBody PreviewRequest request) {
return ResponseEntity.ok()
.contentType(MediaType.APPLICATION_JSON)
.body(new Preview(request.itemCode(), request.quantity(), "preview"));
}
@GetMapping(path = "/order-previews/example",
produces = MediaType.APPLICATION_JSON_VALUE)
public ResponseEntity<Preview> example() {
return new ResponseEntity<>(new Preview("BOOK-001", 1, "preview"),
JsonHeaders.create(), HttpStatus.OK);
}
}例えば、{"itemCode":"BOOK-001","quantity":1}をPOSTすると、同じ値とstatus:"preview"を返します。statusは観測用のラベルです。これで注文が確定した、入力値の業務チェックを満たした、という意味にはしません。ここでは型の選択とJSON出力を確かめるため、入力制約や業務処理を増やしていません。
previewの戻り値がResponseEntity<Preview>なので、本文とContent-Typeを同じ場所で読めます。注釈側のproducesは「返せる形式の条件」、BodyBuilder側は「この応答で指定するContent-Type」です。受け取る型が違っても矛盾ではありません。既存案件では両方を必ず書くと決め付けず、共通の応答方針に合わせます。
HttpHeaders.setContentTypeにもMediaTypeを渡す
GETの見本用メソッドは、ヘッダーを別に作る書き方を確認するための比較例です。JsonHeaders.javaの全文は次のとおりです。
package info.syachiku.mediatype;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
public final class JsonHeaders {
private JsonHeaders() {}
public static HttpHeaders create() {
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
return headers;
}
}headers.setContentType(MediaType.APPLICATION_JSON)の受け側もMediaTypeです。ResponseEntityへ渡したこのヘッダーが、実際の応答でContent-Type: application/jsonになることをGETのテストで確認します。POSTとGETは、同じ画面の保存と参照を実装した一式ではなく、応答の作り方を比較する2つの短い入口です。
なお、HttpHeaders.set(String, String)のように、ヘッダー名と値を文字列で指定するAPIもあります。したがって「ヘッダーなら常にAPPLICATION_JSON」とは覚えません。今回使っている、型を指定したsetContentType(MediaType)の契約を確認します。低水準の文字列設定へ逃がしてエラーだけを消す前に、コードが元々どのAPIで意図を示していたかを見ます。
mvn testの7件と実HTTPの4リクエストで結果を確認する
JDK17とMaven3.9系で、ZIPのpom.xmlがあるフォルダーから実行します。最初の実行で依存がなければネットワークが必要です。JavaCompilerを使うため、Javaを実行するだけのJREではなくJDKを用意してください。
mvn clean test
mvn package
java -jar target/mediatype-type-contract-1.0.0.jar検証した構成はJava17.0.8、Maven3.9.16、Spring Boot3.5.16、Spring Framework6.2.19、JUnit5.12.2です。7テストは、コンパイルの比較3ケースと、HTTP応答の4ケースです。コンパイル比較は各ケースで故障/修正版のソース差分、故障のエラーコード、修正版の成功まで確かめます。
| リクエスト | 入力・見本 | 期待値と実測結果 |
|---|---|---|
POST /order-previews | BOOK-001 / 1 | 200 / application/json / status="preview"、商品コードと個数一致 |
POST /order-previews | PEN-002 / 3 | 200 / application/json / status="preview"、商品コードと個数一致 |
POST /order-previews | 用紙-003 / 2 | 200 / application/json / status="preview"、商品コードと個数一致 |
GET /order-previews/example | BOOK-001 / 1 | 200 / application/json / status="preview"、商品コードと個数一致 |
実JARも127.0.0.1の空きポートで起動し、同じ4リクエストが200、Content-Typeがapplication/json、本文も一致することを確認しました。原本とZIP展開版で照合しています。DBや外部APIへは接続しません。
配布したverify_http.pyを使うなら、ビルド後に次を実行します。Python3が必要です。スクリプトが起動して終了まで行うので、前のコマンドでJARを常駐させておく必要はありません。
python3 scripts/verify_http.py target/mediatype-type-contract-1.0.0.jarテストは故障版の失敗と修正版の応答の両方を検証する
CompilerContractTest.java全文では、通常のビルド対象外に置いた3組を扱います。--release 17と現在のテストのクラスパスを使い、診断コードが想定した1件であることを確認します。依存が見つからないためたまたま失敗した、という状態を成功扱いしません。対応する修正版も同じクラスパスで通ることを検証しています。
CompilerContractTest.javaの全文を見る
package info.syachiku.mediatype;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.Locale;
import java.util.stream.Stream;
import javax.tools.Diagnostic;
import javax.tools.DiagnosticCollector;
import javax.tools.JavaFileObject;
import javax.tools.ToolProvider;
import org.junit.jupiter.api.io.TempDir;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.MethodSource;
import static org.junit.jupiter.api.Assertions.*;
class CompilerContractTest {
record Case(String name, String before, String after, String errorCode) {}
@TempDir Path classes;
static Stream<Case> cases() {
return Stream.of(
new Case("AnnotationObject", "MediaType.APPLICATION_JSON)",
"MediaType.APPLICATION_JSON_VALUE)", "compiler.err.prob.found.req"),
new Case("BuilderString", "contentType(MediaType.APPLICATION_JSON_VALUE)",
"contentType(MediaType.APPLICATION_JSON)", "compiler.err.prob.found.req"),
new Case("AnnotationToString", "MediaType.APPLICATION_JSON.toString()",
"MediaType.APPLICATION_JSON_VALUE",
"compiler.err.expression.not.allowable.as.annotation.value"));
}
@ParameterizedTest(name = "compile negative -> fixed: {0}")
@MethodSource("cases")
void oneChangeFixesTheObservedCompilerFailure(Case sample) throws IOException {
Path broken = Path.of("examples/broken", sample.name() + ".java");
Path fixed = Path.of("examples/fixed", sample.name() + ".java");
String before = Files.readString(broken, StandardCharsets.UTF_8);
String after = Files.readString(fixed, StandardCharsets.UTF_8);
assertTrue(before.contains(sample.before()));
assertEquals(after, before.replace(sample.before(), sample.after()));
Compilation bad = compile(broken, classes.resolve("broken-" + sample.name()));
assertFalse(bad.success());
assertEquals(1, bad.errors().size());
assertEquals(sample.errorCode(), bad.errors().get(0).getCode());
bad.errors().forEach(error -> System.out.printf(
"COMPILER %s line=%d column=%d code=%s message=%s%n",
sample.name(), error.getLineNumber(), error.getColumnNumber(),
error.getCode(), error.getMessage(Locale.ENGLISH).replace('\n', ' ')));
Compilation good = compile(fixed, classes.resolve("fixed-" + sample.name()));
assertTrue(good.success(), () -> good.errors().toString());
System.out.println("FIXED " + sample.name() + " compiled=true");
}
record Compilation(boolean success, List<Diagnostic<? extends JavaFileObject>> errors) {}
private static Compilation compile(Path file, Path destination) throws IOException {
var compiler = ToolProvider.getSystemJavaCompiler();
assertNotNull(compiler, "JDK 17 is required; a JRE alone cannot run these tests");
Files.createDirectories(destination);
var diagnostics = new DiagnosticCollector<JavaFileObject>();
try (var manager = compiler.getStandardFileManager(diagnostics, Locale.ENGLISH,
StandardCharsets.UTF_8)) {
var units = manager.getJavaFileObjects(file);
boolean success = compiler.getTask(null, manager, diagnostics,
List.of("--release", "17", "-encoding", "UTF-8", "-classpath",
System.getProperty("java.class.path"), "-d", destination.toString()),
null, units).call();
return new Compilation(success, diagnostics.getDiagnostics().stream()
.filter(error -> error.getKind() == Diagnostic.Kind.ERROR).toList());
}
}
}OrderPreviewHttpTest.javaは、ResponseEntityのPOST3入力と、HttpHeadersを使うGETの見本1件です。Content-Typeだけでなく、JSON本文に受け取った値とプレビューのラベルがあることを確認します。
OrderPreviewHttpTest.javaの全文を見る
package info.syachiku.mediatype;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
@SpringBootTest
@AutoConfigureMockMvc
class OrderPreviewHttpTest {
@Autowired MockMvc mvc;
@ParameterizedTest(name = "POST JSON: {0}/{1}")
@CsvSource({"BOOK-001,1", "PEN-002,3", "用紙-003,2"})
void responseEntityKeepsRequestValuesAndWritesJson(String itemCode, int quantity)
throws Exception {
mvc.perform(post("/order-previews")
.contentType(MediaType.APPLICATION_JSON)
.accept(MediaType.APPLICATION_JSON)
.content("{\"itemCode\":\"" + itemCode + "\",\"quantity\":" + quantity + "}"))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_JSON))
.andExpect(jsonPath("$.itemCode").value(itemCode))
.andExpect(jsonPath("$.quantity").value(quantity))
.andExpect(jsonPath("$.status").value("preview"));
}
@Test
void httpHeadersSetterAlsoWritesTheExampleAsJson() throws Exception {
mvc.perform(get("/order-previews/example").accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andExpect(content().contentType(MediaType.APPLICATION_JSON))
.andExpect(jsonPath("$.itemCode").value("BOOK-001"))
.andExpect(jsonPath("$.quantity").value(1))
.andExpect(jsonPath("$.status").value("preview"));
}
}故障を検出できるかも、作業用コピーで試しました。POSTの応答ラベルをpreviewからsavedへ替えると、3入力のテストが失敗しました。ヘッダーと200が同じでも、約束した本文が変われば検出できます。ソースを元に戻すと7件が成功し、その復元した版を配布しています。
MockMvcのリクエスト側には、contentType(String)というオーバーロードもあります。今回のテストでMediaTypeを渡しているからといって、Stringを渡す方法がすべて誤りという意味ではありません。contentTypeというメソッド名だけを見ず、MockMvcのリクエストビルダーなのか、ResponseEntityの応答ビルダーなのかまで特定します。
pom.xmlの全文を見る
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-parent</artifactId><version>3.5.16</version><relativePath/></parent>
<groupId>info.syachiku.samples</groupId><artifactId>mediatype-type-contract</artifactId><version>1.0.0</version>
<properties><java.version>17</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding><junit-jupiter.version>5.12.2</junit-jupiter.version></properties>
<dependencies>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
<dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope><exclusions><exclusion><groupId>org.mockito</groupId><artifactId>mockito-core</artifactId></exclusion><exclusion><groupId>org.mockito</groupId><artifactId>mockito-junit-jupiter</artifactId></exclusion></exclusions></dependency>
</dependencies>
<build><plugins>
<plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin>
<plugin><groupId>org.apache.maven.plugins</groupId><artifactId>maven-surefire-plugin</artifactId><version>3.5.6</version></plugin>
</plugins></build>
</project>MediaTypeApplication.javaの全文を見る
package info.syachiku.mediatype;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class MediaTypeApplication {
public static void main(String[] args) {
SpringApplication.run(MediaTypeApplication.class, args);
}
}レビューでは受け側の型と修正後の応答を説明する
レビューで「_VALUEを付けたら直りました」とだけ返すと、次にBodyBuilderで同じミスを繰り返します。今回の要件は、プレビューをJSONで返すことです。選択肢はStringのメディアタイプ定数とMediaTypeオブジェクトで、どちらを使うかは受け側の型によって決まります。
要件:注文プレビューのJSON本文とContent-Typeを返します。保存は行いません。
選択肢:StringのAPPLICATION_JSON_VALUEと、MediaTypeのAPPLICATION_JSONがあります。
採用理由:注釈はString、ResponseEntity.BodyBuilder.contentTypeはMediaTypeを受け取ります。
他手段:注釈にtoString()を足す方法は定数式にならず、コンパイルが通りません。
確認:3組の故障/修正版と、200・Content-Type・JSON本文を7テストで確認しました。- エラーが出た場所のクラス名とメソッドの引数型を確認したか。
- 注釈値ではString型だけでなく定数式の条件も満たしたか。
- 同名のMockMvc APIや低水準のヘッダー設定と混同していないか。
- ビルドが通ることと、実際のContent-Type・JSON本文を確認することを分けたか。
- 故障例を通常のソース配下に混ぜず、失敗すべき例として検証したか。
Springの画面とAPIを一通り作って理解をつなげたい場合に
型の誤りを直した後、Controllerが入力を受け、本文を返す流れを小さなWebアプリで整理したい場合は『作って学ぶ Spring Boot入門』を案内します。この定数を丸暗記するためではなく、画面・Controller・データの受け渡しをつなげる学習の土台としての1冊です。
作って学ぶ Spring Boot入門
Spring Bootを、動くWebアプリを作りながら覚える。
Controller、画面、DB連携などを一つのアプリとして実装できます。Java基礎からSpringの現場へ進む橋渡しに向く一冊です。
- Spring Bootを手を動かして学びたい
- Webアプリ開発の流れをつかみたい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
HTTPメソッドの選択と、JSONをJavaの入力へ渡す仕組みは次の記事で確認できます。型の選択という今回の修正から、API全体の設計へ進むための2本です。
仕様の参照:Spring Framework6.2.19 MediaType、RequestMapping、ResponseEntity.BodyBuilder、HttpHeaders、Java17の注釈値の条件。
JSON定数は名前ではなく受け側の型から選ぶ
注釈のconsumes・producesにはString定数のAPPLICATION_JSON_VALUE、ResponseEntity.BodyBuilder.contentTypeとHttpHeaders.setContentTypeにはMediaTypeのAPPLICATION_JSONを渡します。注釈の中でtoString()を呼んでも定数式にはならないため、型と使える式の条件を一緒に確認します。
修正の合否はコンパイル成功だけで決めず、今回なら200、Content-Type、JSON本文まで照合します。何を返したいのか、どのAPIへ何型を渡すのかを説明できれば、別のメディアタイプや似た名前のAPIでも判断できます。



