MicroProfile Open API を使うと REST API のドキュメンテーションで苦労しなくなる話。

1. RESTful API (JAX-RS)
書くだけで仕様書も
自動で作られていく話
with Eclipse MicroProfile Open API
KOHEI SAITO

2. Who am I
• Name: KOHEI SAITO
• Twitter: @SightSeekerTw
• Qiita: SightSeekerTw
• GitHub: sightseeker

3. みなさん！

4. REST API を実装する
機会増えてますよね

5. サーバサイドは

6. もちろん！
みんな大好き

7. Java

8. クライアントサイド
の開発担当者
はよく困る！
なんなら Ops はもっと困ってる！

9. 開発中
•仕様は
コロコロ
変わる

10. リリース後
• 改修されてるけど
ドキュメントは
更新されてない！

11. 結果

12. 犯人 (担当者) 探し

13. 担当者
に
事情聴取

14. 事情聴取できれば
まだマシ

15. 異動や退職
している
場合も

16. 最悪
リバースエンジニアリング
そして、
デスマーチ突入

17. 仕様変更
要求が起
きると
実装は嫌でも変更す
る
仕様書の変更はされ
ない時がある
スケジュール
優先だし！

18. 目指した
いところ
• 共有してる仕様書が
実装との食い違いを
なくしたい

19. どうしたいか
-----------
-----------
-----------
REST API
のコード
コードから仕様書
をレンダリング
常時
生成

20. 何がいい
のか
•コードから仕様書を
生成するので
仕様書が実装と
食い違いが出ない

21. 実現方法

22. いまどき、REST API の
ドキュメンテーションは
Open API Spec
(旧 Swagger Spec)
がスタンダード！

23. こうしたい！
REST API
の実装コード
Open API Spec
フォーマットのYAML
YAML
生成

25. Eclipse MicroProfile Open API
Eclipse MicroProfile 1.3 で 追加された仕様
JAX-RS Resource から Open API Spec の仕様書
(YAMLまたはJSON) を ダイナミックに生成してくれる
“/openapi” で OpenAPI Spec の
ドキュメントの参照が可能になる

26. つまりこうできる！

27. JAX-RS
Application
with
MP Open API
Open API Spec
フォーマットのYAML
レンダリング
YAML
生成

28. JAX-RS Resource Code
@Path("/book")
public class BookResource {
@GET
@Path("{id}")
@Produces(MediaType.APPLICATION_JSON)
public Book find(@PathParam("id") int id) {
return new Book(0, ”Java本格入門", 3218);
}
}
何の変哲もない タダの JAX-RS Resource コード

29. アプリの
Build & Run
01
/openapi に
HTTP アクセス
02

30. 実装した
JAX-RS
Resource の
Open API Spec
が参照できる

31. 誰でも読めるように
YAML をダイナミックに読んで
ビジュアライズしてくれるように
JAX-RS
Application
with
MP Open API
Open API Spec
フォーマットの
YAMLを
レンダリング
YAML
生成 参照
ひと目にやさしい
ビジュアライズ

32. Swagger UI

33. docker でワンパン起動
docker run
-p 80:8080
-e API_URL=http://localhost:8080/openapi
swaggerapi/swagger-ui

35. エンドポイント
レスポンスのスキーマ

36. どんなエンドポ
イントがあるの
かはわかった

37. でも

38. 説明不足

39. エンドポイントの説明は？
パラメータの説明は？
APIのタイトル・説明は？
レスポンスの説明は？

40. 説明がな
にもない

41. 全体の説明は Open API Spec
{
"openapi": "3.0.1",
"info": {
"title": "Amazoness API (あまぞねす えーぴーあい)",
"description": "書籍管理サービス",
"version": "${project.version}"
}
}
META-INF/openapi.json

42. エンドポイントの説明は
MP Open API の アノテーション
@GET
@Path("{id}")
@Produces(MediaType.APPLICATION_JSON)
@Operation(summary = "本の情報を取得する")
public Book find(
@Parameter(name = "id", description = "ISBNコード", required = true)
@PathParam("id") int id) {
return new Book(0, "Java本格入門", 3218);
}

44. もっと充実するための
MP Open API アノテーション郡
1. @Callback
2. @Callbacks
3. @CallbackOperation
4. @Components
5. @Explode
6. @ParameterIn
7. @ParameterStyle
8. @SecuritySchemeIn
9. @SecuritySchemeType
10. @Extension
11. @Extensions
12. @ExternalDocumentation
13. @Header
14. @Contact
15. @Info
16. @License
17. @Link
18. @LinkParameter
19. @Content
20. @DiscriminatorMapping
21. @Encoding
22. @ExampleObject
23. @Schema
24. @OpenAPIDefinition
25. @Operation
26. @Parameter
27. @Parameters
28. @RequestBody
29. @APIResponse
30. @APIResponses
31. @OAuthFlow
32. @OAuthFlows
33. @OAuthScope
34. @SecurityRequirement
35. @SecurityRequirements
36. @SecurityRequirementsSet
37. @SecurityScheme
38. @SecuritySchemes
39. @Server
40. @Servers
41. @ServerVariable
42. @Tag
43. @Tags

45. さらに、 Swagger UI は！
APIクライアント
としての機能も
兼ね備えている！

46. API コール
レスポンスボデー

47. すごいぜ！
MicroProfile
Open API
と Swagger UI

49. Welcome to Managed Documentation
with MicroProfile Open API

50. 試してみたい方は
“MicroProfile OpenAPI” でググってみてください。
私の Qiita の記事が上の方に出てくるはず。。。
たぶん 5-10 分ぐらいで動かせます。
※ Prerequirements: JDK1.8+

51. Enjoy your
Engineering
Life with
MicroProfile

52. MicroProfile 1.3+ 対応サーバ
MicroProfile Open API に対応していること
改め