TypeScript & Rails プロジェクトに OpenAPI (swagger) の導入を検討する。

Ryosuke Miyamoto 2021/10/08に更新

現状 / 課題

APIが増えてきたのでドキュメント化したい
またTypeScript を導入したので、api レスポンス Type を生成したい
Type を手動で書くならドキュメントの schema から生成したら楽そう
バックエンドは Rspec をしているので自動で schema 生成 ⇨ schema から type 生成すればいいのでは？
いい感じの型が生成されない。自動生成 schema の限界がある？
そもそももっと良い開発フロー & いい感じのフロー移行方法があるか？今ここ

Ryosuke Miyamoto 2021/10/08

Rspec → Schema は rspec-openapi を試している

Ryosuke Miyamoto 2021/10/08

schema から type 生成は openapi-typescript を試している

Ryosuke Miyamoto 2021/10/08に更新

生成した schema → type だと、ほとんどが optional の値になってしまって、思った通りに型を使えない。

? をなくしたい。

schema.ts

export interface paths {
  '/api/posts': {
    get: {
      responses: {
        200: {
          content: {
            'application/json': {
              id?: number
              created_at?: string
              updated_at?: string
              text?: string
            }[]
          }
        }
      }
    }
  }
}

openapi-typescript のオプションに, defaultNonNullable があるが, true にしても ? になってしまう。

Ryosuke Miyamoto 2021/10/08

defaultNonNullable のオプションは、defaultNonNullable && default がある場合になっていたので、rspec-openapi では default の値がないので全て optional になってしまっているっぽい。

id の default 値とかない気がするから、openapi-typescript の仕様の問題な気もする

Ryosuke Miyamoto 2021/10/08

また, rspec-openapi では paths のみで components が入ってこないので、type としては使いづらい（ type の加工大変）

Ryosuke Miyamoto 2021/10/08

そもそも流れとして、すでに Rspec があるから自動で schema を生成したいという感じではあるが、schema を生成してそれを使って test するという流れのが一般的っぽい。

確かに Rspec で api インタフェースは手動で記述してるので、そこをなくして schema を手動で書いて、テストするってのもわかるが、プロジェクトの途中から導入するってケースも多いと思うので、そこまで資産活かして & 段階的に移行する方が良さそうか？

Ryosuke Miyamoto 2021/10/08に更新

type generate メモ

Ryosuke Miyamoto 2021/10/08に更新

schema を使ってテストの方法も調べてみる

スキーマを書くことから始める
OpenAPIで記述した仕様をもとにテストを書くことができるようになったわけですが、これを実際の開発フローでどう活用すると良いか考えてみると、

APIの仕様を検討
仕様が決まったらOpenAPIに則ってドキュメントを書く
ドキュメントをもとにしたテストを書く
API実装
組み込みへパス
というのがいいのかなと思いました。

Ryosuke Miyamoto 2021/10/08

Swagger UI の見た目がなかなかしんどいなぁと思っていたら、
redoc なるものを発見。

デモ

Ryosuke Miyamoto 2021/10/09

stoplight いいかも。見た目の swagger ui の 500倍良い。

schema GUIエディタ & 管理ツール + モックサーバー

https://stoplight.io/

schema を spotlight で考える。
バックエンドはその schema を元に開発 & テスト（comittee など?）
フロントはその schema を元に type を生成できる
フロントはそのまま mock サーバーで開発できる
フロントは cypress などの mock サーバーをバックエンドにできる