REST APIの仕様定義には色々ありますが、Open API Initiativeでも標準ツールとして採用されている SwaggerをつかってAPI仕様を記載しモックアップを作ってみましょう。
Swaggerはユーザが多いのもあって周辺ツールの充実と多言語対応が良いので今から採用するならオススメです。
Swagger.yamlでAPI仕様を記述する。
SwaggerではAPIの仕様をswagger.yamlで記載しますが、
swagger-editorというツールが非常に便利です。
ツールとしてインストールも出来ますし、オンラインでも使えます。
http://editor.swagger.io/#/
まずはこんなyamlを書いてみます。
swagger: '2.0' info: version: "0.0.0" title: サンプル api # Describe your paths here paths: # This is a path endpoint. Change it. /users: get: description: | メンバ一覧取得API. parameters: - name: size in: query description: Size of array required: false type: number format: number responses: # Response code 200: description: ユーザデータ(List) schema: title: ArrayOfUsers type: array items: $ref: '#/definitions/User' /users/{id}: get: description: | メンバ取得API. parameters: - name: id in: path description: user id required: true type: number format: number responses: # Response code 200: description: ユーザデータ schema: $ref: '#/definitions/User' definitions: User: type: object properties: id: type: number name: type: string age: type: number
簡単に言うと、
「/users」で一覧が取得できて
「/users/{id}」でUserID指定のデータが取得出来るというものです。
またdefinitionsのところでUserデータ型を指定しています。
ソースの生成
これで、Springのソースを出力してみましょう。
SwaggerからはNode、GoServer、JAX-RS、Python、Rails等色々な言語の実装を自動生成できますが、SpringBootだと起動が楽なので今回はSpringでいきます。
「Generate Server」から「spring」を選ぶと出来たソースがZipで落ちてくるので解凍するとMavenプロジェクトになっています。
もうこれでサーバの基礎は動きます。
楽勝ですね。
それでは動かしていきます。
まずはPomを開いて42行目あたりの「
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-tomcat</artifactId> <scope>provided</scope> ←この行削除 </dependency>
レスポンス内容をそれらしく作る
Swaggerで生成されるモックはレスポンス内容は空っぽで生成されます。
なのでレスポンス内容は自分でモックコードを書く必要があります。
ソースの中のio.swagger.api.UsersApiControllerを開いて「// do some magic!」と書かれているところにモックコードをこんな感じで書きます。
@javax.annotation.Generated(value = "class io.swagger.codegen.languages.SpringCodegen", date = "2016-11-08T06:41:55.099Z") @Controller public class UsersApiController implements UsersApi { public ResponseEntity<List<User>> usersGet(@ApiParam(value = "Size of array") @RequestParam(value = "size", required = false) BigDecimal size ) { // do some magic! User user1 = new User(); user1.setId(BigDecimal.ONE); user1.setName("aaa"); User user2 = new User(); user2.setId(BigDecimal.TEN); user2.setName("bbb"); List<User> list = new ArrayList<>(); list.add(user1); list.add(user2); return new ResponseEntity<>(list,HttpStatus.OK); } public ResponseEntity<User> usersIdGet(@ApiParam(value = "user id", required = true) @PathVariable("id") BigDecimal id ) { // do some magic! User user1 = new User(); user1.setId(BigDecimal.ONE); user1.setName("aaa"); return new ResponseEntity<>(user1, HttpStatus.OK); }
これでOK。
あとは起動して、「http://localhost:8080/」にアクセスすればSwaggerUIがみれます。
TryItOutをおしてみると
こんな感じで動いていますね。