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

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

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

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

もちろん！
みんな大好き

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 コード

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

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

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

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

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

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

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

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

エンドポイントの説明は
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);
}

もっと充実するための
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

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

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

すごいぜ！
MicroProfile
Open API
と Swagger UI

Welcome to Managed Documentation
with MicroProfile Open API

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

Enjoy your
Engineering
Life with
MicroProfile

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

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

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to RESTful API (JAX-RS) 書くだけで仕様書も自動で作られていく話 with MicroProfile Open API

Similar to RESTful API (JAX-RS) 書くだけで仕様書も自動で作られていく話 with MicroProfile Open API (20)