Spring BootでWeb APIを作ろう

Spring Bootで作るマイクロサービス 第4回

　前回、サンプルアプリケーションを通じて、Spring Bootで利用する基本的なアノテーションについて紹介しました。今回も前回利用したサンプルアプリケーションを通じて、Web APIを実装する際に利用するアノテーションや必要となるSpring Bootの設定方法などを中心に紹介します。

サンプルアプリケーションの概要

　サンプルアプリケーションは、前回と同様で図1に示すような簡単な住所録管理アプリケーションです。

図1：サンプルアプリケーションのイメージ

　このアプリケーションでは、表1のAPIを提供します。

表1：提供するAPI

エンドポイント	HTTPメソッド	概要
/contact/add	POST	新規に連絡先データを登録する
/contact/list	GET	登録してあるデータ一覧を取得する
/contact/item/{id}	GET	指定したidの連絡先データ情報を取得する
/contact/item/{id}	POST	指定したidの連絡先データ情報を更新する
/contact/item/{id}	DELETE	指定したidの連絡先データを削除する

Web APIを実装する（1）

　Spring BootでWeb（REST）システムを構築する場合には、Spring MVCを通常利用します。

Spring Bootを使わないSpring MVCの設定方法

　最初にSpring Bootを使わない場合のSpring MVCの設定方法を紹介します。

　Spring BootからSpring MVCを利用している場合には、Spring MVCがServletを利用したフレームワークであることをあまり意識せずに開発が可能です。

　最近のWebシステムでは、URLとそれに対応する処理を定義するスタイルで開発を進めるのが一般的であり、言語が異なってもおおよそ似た流れで開発が行えます。

　ただし、Servlet APIの知識があると開発していて何か悩んだ場合に、簡単に解決できることもあります。そのため、Spring MVCが通常のServlet APIとしてどのように設定されているのか、知識だけでも知っておくと良いでしょう。

　リスト1はSpring Bootを使わずに、Spring MVCを利用する場合の設定（web.xmlファイル）例です。

［リスト1］Spring Bootを使わない場合のWebコンテナに対してのSpring MVCの設定方法

<?xml version="1.0" encoding="ISO-8859-1"?>
// （省略)
<servlet>
    <servlet-name>dispatcher</servlet-name>
    <servlet-class>
        org.springframework.web.servlet.DispatcherServlet  // (1) 利用するサーブレットクラス
    </servlet-class>
    <init-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>/WEB-INF/spring/dispatcher-config.xml</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
</servlet>

// (2) URLと動作するサーブレットの関係
<servlet-mapping>
    <servlet-name>dispatcher</servlet-name>
    <url-pattern>/</url-pattern>
</servlet-mapping>
//  (省略)

　（1）では、Spring MVCのサーブレットであるDispatcherServletクラスを登録します。次に、（2）ですべてのパス("/")のリクエストを（1）で登録したサーブレットが処理をするように指定します。

　つまり、図2の関係でSpring MVCはサーブレットAPIを通じて実装されています。

図2：DispatcherServletクラスとSpring MVCとの関係

Spring MVCのControllerを定義する

　Spring MVCのControllerを定義する場合には、@Controllerと@RequestMappingというアノテーションを使ってControllerを定義します。

　リスト2はサンプルアプリケーションでのControllerの定義例です。

［リスト2］Controllerの定義例（java/src/main/java/com/coltware/contacts/controller/ContactController.javaの抜粋）

@RestController      // (1) WEB Controllerとして機能するためのBean登録
@RequestMapping("/contact")  // (2) リクエストURLの指定
@Scope("request")    // (3) オブジェクトのスコープ
public class ContactController {
  // (省略)
}

　（1）では、@RestControllerというアノテーションを使っていますが、こちらはRest APIとして動作させるための@Controllerと@ResponseBodyを、1つのアノテーションとして指定しています。

　続いて、（2）ではリクエストURLの指定をします。最低これら2つの指定をしますが、（3）のようにControllerオブジェクトのライフタイムスコープについて指定することもあります。

リクエストURLを定義するアノテーション

　Spring MVCのリクエストとのマッピングを定義するには、@RequestMappingアノテーションを利用します。

　@RequestMappingアノテーションは、クラスとメソッドに指定が可能であり、クラスに指定する場合には図3のように各メソッドで指定するパスの親パスとして扱われます。また、表2のような属性が指定が可能です。

図3：RequestMappingでのクラスとメソッドの関係

表2：RequestMappingで指定可能な属性

属性	概要
value（path）	リクエストパス（pathというパラメータでも可能）
method	受け付けるHTTPメソッド（GET,POST,PUT,DELETEなど）
params	指定するリクエストパラメータの有無（Rest APIなどを実装する場合にはあまり利用しません）
headers	リクエスト時のヘッダの有無
consumes	リクエストのContent-Typeの指定（Rest APIの場合には、application/jsonなどを指定する）
produces	リクエストのAcceptの値の指定

　リスト3はサンプルアプリケーションでの利用例です。

［リスト3］@RequestMappingの利用例（java/src/main/java/com/coltware/contacts/controller/ContactController.javaの抜粋）

// (1) 基本的な利用例
@RequestMapping(value = "/add", method = RequestMethod.POST, consumes = "application/json") 

// (2) PostMappingの利用例
//  @PostMapping(value = "/add",consumes = "application/json") 

// (3) パス指定だけのPostMappingの利用例
//  @PostMapping("/add")  
public Response addAction(@RequestBody(required = false) ContactModel item){
    //  (省略)
}

　（1）は、/contact/addというURLに対してPOSTメソッドでJSON形式のリクエストに一致します。また、POSTメソッドに対応する場合にはmethodを（2）のように、@PostMappingというアノテーションが利用可能です。

　同様に、GETメソッドでは@GetMapping、PUTメソッドでは@PutMapping、DELETEメソッドでは@DeleteMappingが利用可能です。

　また、パスだけの指定の場合には、（3）のように記述可能です。