OpenAPIを利用した開発

June 5, 2019 usumachi OpenAPI API OpenAPI Swagger API

概要

今回は、OpenAPI Specification(以下OAS)駆動でREST API開発をすることで享受できる恩恵と制限についてお伝えできればと思っています。

序文

MF KESSAI(以下MFK)で、Backend開発を行っているusumachi(a.k.a usuimachinami)と申します。 開発に対し “気合ブリバリ” でそれはもう横須賀最強 麓沙亜鵺です。

さて、MFKでは導入企業様のさらなる請求業務の効率化を目指し、REST APIを提供しています。 開発に際してインターフェースの仕様定義のために、OASを利用して開発を行っています。

また、最近のMFKは試作（prototyping）を繰り返してより良いものを作ろうという動きがあります。 この方針とOASを利用した開発がとても適合しました。

OpenAPIとは

OASとは正式名称でOpen API Specificationのことを指しています。OASと略されます。 REST APIのインターフェース記述を標準化するための仕様です。現在はOpen API initiativeという団体によって運営されています。

特徴

  • json or yaml形式で記述される
  • 特定の言語に依存しない
  • 人間が理解しやすい
  • コンピューターが理解しやすい

私見ですが、立ち位置としては上記の特徴からもgRPCと近いと思います。 マイクロサービスの文脈でも各サービス間のインターフェースとして利用価値があると考えられます。

元々Smart Bearの開発していたSwaggerがOpen API initiativeに寄贈され、OASとして名称変更されました。 Swaggerのほうが馴染み深い人も多いと思います。Swagger2.0はOpenAPI2.0と対応しています。

2019.06現在ではOpenAPI 2.xとOpenAPI 3.xのに系統があります。

恩恵

OpenAPIを利用していてよかった！と感じた内容は以下の通りです。

  • 開発の速度が向上する！？
    • Documentが生成できる
    • MockServerが簡単に用意できる
    • Codeがインタフェースから生成できる
  • クライアント側の開発コストが削減できる！？
  • インターフェースがRESTfulに矯正される！？

順に説明していきます。

開発の速度が向上する！？

OASは標準仕様であるため、その周りに沢山のツールが有志によって作られています。 https://openapi.tools/

また、Smart BearもSwaggerとして、OpenAPI向けに非常に強力なツールを提供しています。https://swagger.io/

個人差はあると思いますが、APIの仕様検討段階では下記のような気持ちが強くなってきます。

  • 理解しやすいドキュメントが見たい
    • インターフェースのレビューを楽にしたい
    • 全体像の把握をしたい
  • 実際に動くモックサーバーが欲しい
    • クライアントの試作をしたい
    • インターフェース上のバグを発見したい
  • コストをかけずに試作したい
    • 早いサイクルで試作を繰り返したい
    • 駄目なものはすぐに捨てたい

OASはこれらに”答え”をもたらします。

例えばSmart BearのSwaggerHubを利用すれば、ブラウザ上のeditorにインターフェース定義を書いていくだけで見やすいドキュメントとモックサーバーが立ち上がります。

また、複数のツールが各プログラミング言語向けにインターフェース定義からサーバーコードを生成する機能を提供しているのでサクッと試作してみることができます。

クライアント側の開発コストが削減できる！？

サーバーコード同様にクライアント側のコードも生成してくれるツールが揃っています。 各言語ごとのSDK提供に近いことが実現され、API利用側のコストを削減できる可能性があります。 実際にMF KESSAIではこれが導入の大きな決め手となりました。

インターフェースがRESTfulに矯正される！？

OASは多くのREST API開発に利用されています。言うなれば”こすられている”ので極めて”RESTful”になっています。OASに則ってインターフェースを考えていくと自然に”RESTful”な設計に矯正されていきます。

制約

便利で愛すべきOpenAPIですが、適合しない仕様も存在します。

  • OASの仕様から外れる仕様が難しい！？
  • OpenAPI 3.0周りのツールが発展途上！？

OpenAPIの仕様から外れる仕様が難しい！？

OASは標準仕様であるため、そこから外れる仕様を利用した場合、周辺ツールなどが対応していない可能性があります。コード生成などの恩恵が得られないこともあるので、なるべく道を外れないようにしたいですね。

ただ、x-something-originalというように独自の仕様定義を行うこともできます。 OASのjson/yamlを解析するツールもあるので、これを利用して独自にコード生成ツールを作成することも比較的”カンタン”です。

OpenAPI 3.0周りのツールが発展途上！？

OpenAPI 3.0が公開されたのは2017.07のことです。その周辺のツールはまだ発展途上の感があります。Swagger2.0対応の安定したツールが数ある一方で、OpenAPI 3.0に対応していないツールもあります。

また2.0 -> 3.0という変換は可能ですが、逆は難しくツールをお見かけしたことはありません。

つまり、新しい方が良いとは一概に言い難く、利用したいツールや仕様によって慎重にバージョンを選択する必要があります。

おわりに

MF KESSAIではツールなどの状況や3.0へ移行できるという点から2.0を利用することに決めました。 鋭意開発中のプロダクトもあるので、知見が溜まった折にはまた発信していきたいと考えています。

“いかがでしたでしょうか？”。

もっと詳しい話を聞きたい方、OpenAPIなどを用いたサービスやGolangを用いたAPI開発に興味ある方はぜひお気軽にMF KESSAIへ遊びにきてください！　 ご連絡はこちらからお願いします。

RECENT ENTRIES
ARCHIVES
ABOUT