OpenAPI + LaravelでWebAPI実装を楽にしたい ~１. OpenAPIとスキーマ駆動開発（SDD）について~ - アドグローブブログ

はじめに

こんにちは。ゲーム事業部（大阪）サーバーサイドエンジニアの波多野です。
突然ですが、皆さんOpenAPIは利用していますか？
OpenAPIという言葉に耳馴染みがなくても、Swaggerならご存知の方も多いのではないでしょうか。

今回は、
「PHPのフレームワーク LaravelとOpenAPIを組み合わせて、WebAPIの実装を少しでも楽にできないか」という挑戦を連載にしてみたいと思います。
具体的には、OpenAPIで作成した仕様を元にドキュメント、コード、モック、単体テストを自動生成・実行する、スキーマ駆動開発を実現することがゴールです。

第１回目の本記事では、OpenAPIとスキーマ駆動開発についてご紹介します。

はじめに
OpenAPIとは
Swaggerとは
スキーマ駆動開発とは
- メリット
- デメリット
次回

OpenAPIとは

OpenAPIとはREST APIの仕様を定義するフォーマットです。
APIのリクエストパラメータ、レスポンスパラメータ、エラーレスポンスのパターン、API間で共通で利用する構造体などのフォーマットを、YAML形式やJSON形式で記述する事ができます。
例えば、以下のようなものです。
（Swagger UIのデモページで使用されているYAMLから一部抜粋、一部省略）

---
swagger: "2.0"
info:
  description: "This is a sample server Petstore server.  You can find out more about\
    \ Swagger at [http://swagger.io](http://swagger.io) or on [irc.freenode.net, #swagger](http://swagger.io/irc/).\
    \  For this sample, you can use the api key `special-key` to test the authorization\
    \ filters."
  version: "1.0.6"
  title: "Swagger Petstore"
    :
    :
paths:
  /pet/{petId}/uploadImage:
    post:
      tags:
      - "pet"
      summary: "uploads an image"
      description: ""
      operationId: "uploadFile"
      consumes:
      - "multipart/form-data"
      produces:
      - "application/json"
      parameters:
      - name: "petId"
        in: "path"
        description: "ID of pet to update"
        required: true
        type: "integer"
        format: "int64"
      - name: "additionalMetadata"
        in: "formData"
        description: "Additional data to pass to server"
        required: false
        type: "string"
      - name: "file"
        in: "formData"
        description: "file to upload"
        required: false
        type: "file"
      responses:
        200:
          description: "successful operation"
          schema:
            $ref: "#/definitions/ApiResponse"
      security:
      - petstore_auth:
        - "write:pets"
        - "read:pets"

Swaggerとは

SwaggerとはOpenAPIで記述された仕様を便利に利用する為のツール群です。
そのツール群の中の一つSwagger UIは特に有名ではないでしょうか。
Swagger UIを利用すると、以下のようにAPIリファレンスをブラウザ上で分かりやすく見せることができます。（Swagger UIのデモページから引用）他にもOpenAPIエディタのSwagger Editorや、OpenAPI仕様からコードを自動生成するSwagger Codegen等があります。

Swaggerの他にもOpenAPIを利用する為のツールが沢山あります。
例えば、OpenAPI仕様を元にモックサーバーを作成したり、仕様通りの実装ができているかの確認を行う単体テストが実行できるツールなどがあります。

スキーマ駆動開発とは

テスト駆動開発（TDD）、モデル駆動開発（MDD）、ドメイン駆動開発（DDD）など多種多様な開発手段がありますが、その一つです。
その名の通り「スキーマ（仕様）を先に定義して、それに沿って開発を進めましょう」という手法です。
こう書くと「何を当たり前の事を言ってるんだ」という感じですが、「仕様のフォーマットをガチガチに固めて、開発の一部分を自動化してしまう」という所に、この開発手段の強みがあります。

OpenAPIで作成されたAPI仕様を元にして、リファレンスドキュメント制作、モックサーバー立ち上げ、コード実装、単体テストを行い、効率よく開発していくのが、この開発手法の主たる流れです。

メリット

スキーマ駆動開発を導入することで以下のようなメリットがあります。

API仕様書のフォーマットが統一される

API仕様書を書くツールとしてExcelなどがよく利用されますが、これは企業や人によってフォーマットやルールが異なります。
OpenAPIという共通化された規格を使用することで、どこでも誰でも同じフォーマットで記述することが可能です。

リファレンスドキュメントを自動生成できる

上で紹介したSwagger UIやReDocなどを利用することで利用者向けのリファレンスドキュメントを生成することが可能です。
APIの利用者に対して、常に正確で最新のドキュメントを提供することができます。

コードを自動生成できる

Swagger CodegenやOpenAPI Generatorを利用することで、仕様からコードを自動生成することができます。
エンジニアは自動生成されたコードに沿ってビジネスロジックを実装するだけでよくなるので、実装方法の共通化をしつつ手間を減らすことができます。

モックサーバーが作成できる

API Sproutなどを利用してOpenAPIからモックサーバー（仮のレスポンスだけを返すサーバー）を作成することができます。
「APIの実装が完了するまでクライアントサイドの作業が進められない」といったボトルネックが解消できるでしょう。

仕様を元に単体テストができる

実際にAPI実装を進めていくなかで、仕様通りのレスポンスを返さない誤った実装をしてしまうミスが多少なりとも発生します。
openapi-validatorのようなものを利用することで、OpenAPI仕様とAPIレスポンスを比較して簡易的に単体テストを行うことが可能です。

デメリット

こう書くと良い事だらけのように見えますが、もちろんデメリットもあります。

学習コストが高い

Swagger UIでドキュメントを作成するだけであれば多少省略して記述しても問題はないのですが、各種ツールをきちんと利用するためにはOpenAPIの記法を正確に則る必要があります。
そのためには覚えることが沢山あり、お手軽に導入できるものとは言えません。

OpenAPIでは対応しきれない仕様がある

規格を厳密にすればするほど、柔軟性は失われてしまいます。
OpenAPIでは表現しきれない仕様が出てきた場合、スキーマ駆動開発は破綻してしまうでしょう。
実際にあった事例として、RESTでないAPIの仕様を作成しようとするとOpenAPIでは表現できない事が多かったです。
また、利用したいツールが実現したい仕様に対して対応しきれていない場合もあります。

そういった問題に直面した場合は、仕様の方を調整するかツールを独自にカスタマイズする必要が出てきます。

次回

次回はDockerを用いて、Swagger UIとSwagger Editorを実際に利用してAPI仕様を定義できるところまで実践する予定です。最後までお読みいただきありがとうございました！

現在アドグローブではゲームエンジニアを含め、さまざまなポジションで一緒に働く仲間を募集しています。
詳細については下記からご確認ください。みなさまからのご応募お待ちしております。

hrmos.co