Open11

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

Ryosuke MiyamotoRyosuke Miyamoto

現状 / 課題

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

生成した 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 MiyamotoRyosuke Miyamoto

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

Ryosuke MiyamotoRyosuke Miyamoto

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

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

Ryosuke MiyamotoRyosuke Miyamoto

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

https://gift-tech.co.jp/articles/schema-first-api-development/

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

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

https://gift-tech.co.jp/articles/openapi-generator-typescript/

Ryosuke MiyamotoRyosuke Miyamoto

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

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

https://stoplight.io/

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