Download to read offline
![$ref を解決できない 😇
�28
$ openapi-generator validate -i kamakura/openapi.yaml
Validating spec (kamakura/openapi.yaml)
Errors:
-attribute paths.'/users/
{id}'(get).responses.responses.$ref is not of type
`object`
[error] Spec has 1 errors.](https://image.slidesharecdn.com/kamakura-190623062822/75/OpenAPI-3-0-microservice-API-28-2048.jpg)
![[出張！雲勉 in Tokyo] Swagger で簡単APIドキュメント作成](https://cdn.slidesharecdn.com/ss_thumbnails/random-160831072101-thumbnail.jpg?width=640&height=640&fit=bounds)
OpenAPI 3.0でmicroserviceのAPI定義を試みてハマった話
- 1. OpenAPI 3.0 で microserviceの API 定義を試みてハマった話 小池 大地 kamakura.go #5 2019/06/22
- 2. 本日のおはなし • OpenAPI 3.0の yaml ファイルを分割管理しようとし た • $ref で死にまくったので $ref を解決するツールをプロ ジェクトで自作した • 人間と機械でそれぞれ触る yaml を分けるという方法 をとった • OpenAPI のツールチェインはよく調べたほうがいい �2
- 3. OpenAPI • Google、マイクロソフト、IBM などが立ち上げたOpen API Initiative が提唱する REST API の I/F 記述フォー マット（OpenAPI Specification) • Swagger がベース • 3.0 と 2.0 で大分仕様が違っており、今回は 3.0 の話 • https://github.com/OAI/OpenAPI-Specification �3
- 4. OpenAPI https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v3.0/petstore.yaml �4 paths: /pets: get: summary: List allpets operationId: listPets tags: - pets parameters: - name: limit in: query description: How many items to return at one time (max 100) required: false schema: type: integer format: int32 responses: '200': description: A paged array of pets headers: x-next: description: A link to the next page of responses schema: type: string content: application/json: schema: $ref: "#/components/schemas/Pets"
- 5. 導入プロジェクト • 社内コーポレートエンジンの開発プロジェクト • 名簿、評価、サイコロ給、スマイルなど複数のサービス が連携して一つのプロダクトとして稼働する •各サービス、フロントエンドは別々の開発者が開発する �5
- 6.
- 7. 導入経緯 • BFF、バックエンドサービス、フロントエンドが同時に開 発が進む • 先に各サービス間のI/F を決め、レビューしてOKだった ら実装に着手するというワークフロー • よし API I/F を OpenAPI Spec で書こう • code generate や request/response の validate もできる • 世は大 OpenAPI 時代!! �7
- 8. 各 I/F をOpenAPI で定義 �8
- 9.
- 10. API は 2倍 •認証は BFF が行うため全リクエストは BFF 経由する • つまり API は 2倍 必要 �10 /users/1
- 11. yaml で病むる • 膨大な数のAPI になるため yaml は分割して管理した い • 評価のシステムの管理画面だけで 40 API ある（BFF 含めると 80 API）。管理系だけで1万行になった • yaml 分けたいけど entity とか再定義するのはミスも 多発するだろうしいい感じに使いまわしたい • 2．0 は yaml マージツールがある https:// www.npmjs.com/package/multi-file-swagger �11
- 12. components 3.0 では再利用する定義を componentsに集約できる �12 https://www.openapis.org/news/blogs/2016/10/tdc-structural-improvements-explaining-30-spec-part-2
- 13.
- 14. プロジェクト自作 yaml merger •node.js 製 • https://github.com/whitlockjc/json-refs を使い 別ファイルの $ref を解決してマージした yaml を生成 する • @dameleon++ �14
- 15. もともとはこう �15 paths: /users/{id}: get: - - responses: "200": content: application/json: schema: $ref: "#/components/schemas/User" components: schemas: User: title:MyUser type: object properties: id: type: integer name: type: string
- 16.
- 17. entities.yaml �17 User: title: MyUser type: object properties: id: type:integer name: type: string
- 18. merger で $ref解決 �18 paths: '/users/{id}': get: - - responses: '200': content: application/json: schema: title: MyUser type: object properties: id: type: integer name: type: string
- 19. ちょっとまった • $ref で別ファイルの定義を参照するのはOpenAPI 3.0 の仕様にそもそもあるのでは?? • あります!! • ただしツールによってはサポートしていなかったり、多段 $ref はスルーされたりします • 他にも細かい制約があります �19 仕様: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#relative-references-in-urls
- 20. 多段 $ref 名簿側の Userの定義を BFF で使いまわしたい �20 /users/1
- 21. たとえばこんなディレクトリ構成 �21 . !"" kamakura # !""entities.yaml # $"" openapi.yaml !"" kamakura-bff $"" openapi.yaml
- 22.
- 23. kamakura-bff/openapi.yaml �23 paths: /users/{id}: get: - - responses: $ref: "../kamakura/openapi.yaml#/paths/ ~1users~1{id}/get/responses" responseのステータスコード、entity の定義を $ref で 引き込みたい ~1 は / のエスケープ文字
- 24. Swagger UI で開くと😱 �24
- 25. merger で $refを解決すると 😊 �25
- 26. 多段 $ref 問題 •kamakura-bff/openapi.yaml -> kamakura/ openapi.yaml -> kamakura/entities.yaml この $ref を Swagger UI は解決できない • ツールによっては最初の $ref で解決できなくて死ぬも のもある �26
- 27. $ref 問題 • https://github.com/OpenAPITools/openapi- generator •generate した model を使っている �27
- 28. $ref を解決できない 😇 �28 $openapi-generator validate -i kamakura/openapi.yaml Validating spec (kamakura/openapi.yaml) Errors: -attribute paths.'/users/ {id}'(get).responses.responses.$ref is not of type `object` [error] Spec has 1 errors.
- 29. 開発フロー • merger で生成された$ref 解決済みの yaml に対し て validation をかけている • 人間が触る yaml と機械が 触る yaml を分ける • テストで request/response の validate に使いたい ので pre-commit hook で $ref 解決済み yaml を生 成して commit している • invalid な yaml が生成されても validation をすり抜 けることもあるので Swagger UI で表示してみて問題 ないか確認するのが良い �29
- 30.
- 31.
- 32.
- 33.
- 34.
- 35. paths 直下は $refを使えない �35 https://swagger.io/docs/specification/using-ref/
- 36.
- 37. ハマりポイント • JSON Schemaと完全に同じではない • JSON Schema では valid だが OpenAPI では invalid になることがある!! • 各ツールの仕様の網羅具合がまちまちなのもあり根気 強く向き合う覚悟がいる �37
- 38. �38 何はともあれ merger で $refを解決すればいけそう?
- 39. 一部の定義だけ override したい •バックエンドサービスとのやり取りで request ID やトレー シング用の trace ID をヘッダで引き回したい • code generate した際に BFF とバックエンドサービス の struct の名前が重複するので title（これが go の struct の名前になる） を変更したい • サービス側の定義を $ref で引き込みつつ、該当箇所 だけ定義を上書きするというやり方でこれらを実現した い • allOf を使うことで引き込んだ定義に手を加えることが できる �39
- 40. parameters を overrideしたい �40 kamakura/openapi.yaml paths: /users/{id}: get: parameters: - name: id in: path required: true schema: type: integer format: int64 - name: request_id in: query required: true schema: type: string BFF 側で request_id を ヘッダに入れてバックエンド サービスに渡す
- 41. parameters を overrideしたい �41 kamakura-bff/openapi.yaml paths: /users/{id}: get: allOf: - $ref: "../kamakura/openapi.yaml#/paths/ ~1users~1{id}/get" parameters: - name: id in: path required: true schema: type: integer format: int64 BFF 側は allOf で引き込んだ parameters に対して 後から override している
- 42. request_id が消えないぞ?? �42 merger yaml paths: /users/{id}: get: parameters: -name: id in: path required: true schema: type: integer format: int64 - name: request_id in: query required: true schema: type: string
- 43.
- 44. わざとらしく name: hogeにする �44 kamakura-bff/openapi.yaml paths: /users/{id}: get: allOf: - $ref: "../kamakura/openapi.yaml#/paths/ ~1users~1{id}/get" parameters: - name: hoge in: path required: true schema: type: integer format: int64
- 45. ほげええええ �45 merger yaml paths: /users/{id}: get: parameters: - name:hoge in: path required: true schema: type: integer format: int64 - name: request_id in: query required: true schema: type: string
- 46. 最終的にこうなる �46 paths: /users/{id}: get: summary: $ref: "../kamakura/openapi.yaml#/paths/~1users~1{id}/get/responses" description: $ref: "../kamakura/openapi.yaml#/paths/~1users~1{id}/get/description" responses: $ref:"../kamakura/openapi.yaml#/paths/~1users~1{id}/get/responses" parameters: - name: id in: path required: true schema: type: integer format: int64 上書きたい要素を引き込まずに再定義する
- 47. yaml で病むる • microservicesをやろうとするとこうなってしまうので は…？ • みなさんは一体どうやっているのか…もっといいやり方 あるのでは…？ �47
- 48.
- 49. openapi-generator generate • model、apiclient あたりの利用に留めておくのがよい という所感 • api client は interface は生成されないので generate されたコードに対して自前で interface を生 やすか生 struct をそのまま触ることになる • テストのときに mock するといったことがやりにくいので 悩ましい �49
- 50. model_my_user.go �50 /* * kamakura BFFAPI * * No description provided (generated by Openapi Generator https:// github.com/openapitools/openapi-generator) * * API version: 1.0.0 * Generated by: OpenAPI Generator (https://openapi-generator.tech) */ package openapi type MyUser struct { Id int32 `json:"id,omitempty"` Name string `json:"name,omitempty"` }
- 51. generate まわり • 2.0では https://github.com/go-swagger/go- swagger というのがあるので 2.0 ではこちらを検討し てもよいかも • コードや GoDoc から yaml を生成するという方法もあり • 人間のドキュメンテーション用など厳密な定義が必要な い場合は今回取り上げた内容でも許容できるところもあ ると思うので、チームとしてどこまで OpenAPI に求める か次第 �51
- 52. お世話になっているもの • request/response validation https://github.com/getkin/kin-openapi •mock server https://github.com/danielgtaylor/apisprout �52
- 53. 本日のおはなし • OpenAPI 3.0の yaml ファイルを分割管理しようとし た • $ref で死にまくったので $ref を解決するツールをプロ ジェクトで自作した • 人間と機械でそれぞれ触る yaml を分けるという方法 をとった • OpenAPI のツールチェインはよく調べたほうがいい �53
- 54.