Rustで始めるコードファーストなOpenAPI定義の生成 🦀

Rust、何もわからない... #9
https://estie.connpass.com/event/289216/

Transcript

1. Rustで始めるコードファーストな OpenAPI定義の生成 🦀 Takayuki Maeda / TaKO8Ki
2. • Rust committer (member of compiler contributors team and diagnostic working group) • Software Engineer @Moneyforward Takayuki Maeda / TaKO8Ki @TaKO8Ki @TaKOBKi
3. 何を作っているか？
4. 何を作っているか？ ref: https://corp.moneyforward.com/news/release/service/20230216-mf-press/
5. 何を作っているか？ 国際規格「Peppol（ペポル）」とは、受発注や請求にかかる電子文書をネットワーク上で やり取りするための「文書仕様」「ネットワーク」「運用ルール」の規格で、国際的な非営 利組織であるOPEN PEPPOLが管理しているグローバルな標準規格

6. What is Peppol? ref: Introduction to Peppol AS4 12
7. What is Peppol? ref: Introduction to Peppol AS4 12 電子文書はXMLでやり取りされ る
8. What is Peppol?
9. What is Peppol?
10. What is Peppol?
11. 何を作っているか？ 自分がいるチームではこのSMPとAccess Pointのラッパー・請求書のvalidatorである Peppol APIをRustで開発している。

12. コードファーストな OpenAPI定義の生成を したい
13. コードファーストなOpenAPI定義の生成をしたい Peppol APIはマネーフォワードの各プロダクトで利用されるマイクロサービスなので、 RESTful APIのインターフェイスを定義したい。

14. コードファーストなOpenAPI定義の生成をしたい Peppol APIはマネーフォワードの各プロダクトで利用されるマイクロサービスなので、 RESTful APIのインターフェイスを定義したい。加えてできるだけ実装と対応した定義に したい。

15. Invoice XML is complicated and has “161” elements and some attributes. コードからOpenAPI documentationを生成し たい
16. コードファーストなOpenAPI定義の生成をしたい そこで便利なのが utoipa というcrate
 utoipa - Simple, Fast, Code first and Compile time generated OpenAPI documentation for Rust

17. 例えばこんな感じでattributeを使ってpathを定義できる
18. 例えばこんな感じでattributeを使ってpathを定義できる
19. こんな感じでderiveを使ってschemaを定義できる
20. こんな感じでderiveを使ってschemaを定義できる
21. Doc用のstructをOpenApi deriveをつけて定義して、
22. Documentation用のstructをOpenApi deriveをつけて定義して、
23. こんな感じで定義を出力できます
24. もしくは、こんな感じでroutingを設定すると/swagger-uiでSwagger UIが見 られる
25. コードファーストなOpenAPI定義の生成をしたい 総じてすごく使いやすい。特にstructにattributeとしてdescriptionやexampleを書け るのがメンテナンスしやすくて良い。

26. コードファーストなOpenAPI定義の生成をしたい ただ気をつけないといけないこともある。
 

27. コードファーストなOpenAPI定義の生成をしたい 例えば、utoipaでは、$refでスキーマなどにアクセス可能かどうかは自分達で担保する必要が ある。
 
 > Note! Utoipa does not guarantee that free form ref is accessbile via OpenAPI doc or Swagger UI, users are eligible to make these guarantees.
 
 
 
 ref: https://docs.rs/utoipa/latest/utoipa/attr.path.html#request-body-attributes
28. どういうことかというと、例えばこれは、
29. こうなって、
30. Tagをschemasに追加し忘れると存在しないschemaを参照してしまう
31. また例えば定義されていない型をbodyとして指定すると、
32. 普通にコンパイルが通り、refになってしまう
33. コードファーストなOpenAPI定義の生成をしたい ToSchema derive、path attributeでは、ユーザーが定義したものについてはrefで参 照するような実装になっている。つまり、すごく大きなStructなどを扱う時に全ての Struct・Enumをschemaとして追加しないといけない？

34. 壊れにくいOpenAPI 定義を作るために
35. 壊れにくいOpenAPI定義を作るために まず、新しいpathやschemaを追加した時に、存在しないschemaを参照してOpenAPI 定義が壊れにくいようにしたい。

36. そんな時に使えるのが #[schema(inlline)]。これをもとに定義を作ると、
37. こんな感じでtagがinline化される
38. 壊れにくいOpenAPI定義を作るために これによって存在しないスキーマを参照することを防げる。
 
 ただ個人的にはデフォルトがinlineでrefにしたい時だけ#[schema(ref)]にするみたい な実装の方がユーザ的には使いやすいんじゃないかと思う。結構大きな変更なのでプ ルリク投げるか難しいところ。

39. 壊れにくいOpenAPI定義を作るために 次に、定義してない型を指定した時にコンパイルエラーになって欲しい。

40. これも同じようにpathでinlineを使うことで一応防げる。 下記はコンパイルエラーになる。
41. 壊れにくいOpenAPI定義を作るために 本当はinline無しでも定義してない型はコンパイルエラーになって欲しい。

42. Invoice XML is complicated and has “161” elements and some attributes. じゃあなぜこういう実装になってるのか？
43. Invoice XML is complicated and has “161” elements and some attributes. ここで少し実装を覗いてみる
44. 壊れにくいOpenAPI定義を作るために まず、 cargo-expand でpathがどういうコードを生成するのか覗いてみる。

48. utoipa-gen/src/component.rs:746:759
49. utoipa-gen/src/component.rs:746:759 受け取ったpathをstringに そのnameを渡しているのでコンパイルエラーにな らない。
50. Invoice XML is complicated and has “161” elements and some attributes. じゃあinlineの時はどうなってるか？
51. utoipa-gen/src/component.rs:726:740 type_pathがstringに変換されずにそのまま 使われている
52. utoipa-gen/src/component.rs:726:740 type_pathがstringに変換されずにそのまま 使われている じゃあこれをnot inlineでも実現すればいいのでは？
53. 壊れにくいOpenAPI定義を作るために 色々みるとpathのbodyなどには定義された型以外も渡ってくることが判明した。

54. asを使って代替pathを設定でき、これがbodyとして使える。
55. asを使って代替pathを設定でき、これがbodyとして使える このケースでコンパイルエラーになってはいけない
56. 壊れにくいOpenAPI定義を作るために 最終的にbodyに定義されていない型が来たときにコンパイルエラーにする実装を途中 まで書いていたところでこれに気づいて断念した。

57. Invoice XML is complicated and has “161” elements and some attributes. 元の話に戻ります
58. 壊れにくいOpenAPI定義を作るために 壊れにくいOpenAPI定義を作るためにというか、openapi.yamlと実装に差分が出ない ように別クレートを作ってunit testをその中に含めている。

59. コードから生成したものと実際の openapi.ymlに差分 があるかチェックし、あれば更新を促している。
60. まとめ
61. © Money Forward, Inc. まとめ • Rustでは、utoipaを使ってコードファーストなOpenAPI定義の生成ができ る。
 • utoipaは気をつけるべきポイントはあるが、総じて使いやすい。
 • 疑問点があったら実装を覗いてみて改善点があればパッチを投げてみる のが良さそう。
 
 自分は最終的にtypo修正だけして終わりました。
 https://github.com/juhaku/utoipa/pull/669

62. Invoice XML is complicated and has “161” elements and some attributes. We are hiring!