アルパカログ

プログラミングとマネジメントがメインです。時々エモいのも書きます。

OpenAPIとAPI Sproutを使ったら開発体験がすごく良くなった話

Web開発の現場では、APIを境界にしてサーバー側、クライアント側で分担して開発を進めるのはよくあることだと思います。

そんなとき問題になるのが「API仕様の表現が人によってバラバラ」「ダミーのAPIレスポンスを用意するのが面倒」といったことです。

これらの問題は、API仕様のフォーマットである OpenAPI と、OpenAPI 仕様を元にコマンド1発でダミーのAPIサーバーを立ててくれる API Sprout を使うことで解決することができます。

OpenAPI + API Sprout という組み合わせは、控えめに言っても開発体験がかなり良いです。

ぜひ皆さんにも試してほしいのでご紹介します。

OpenAPI Specification

OpenAPI Specification は言語に依存しない、人間にもコンピュータにも理解しやすい RESTful API の仕様です。

と、言われてもピンと来ないと思いますので、下記に例を示します。

openapi: 3.0.2
info:
  title: Example API
  version: 0.0.1
servers:
- url: http://localhost:3000/
paths:
  /users/{userId}:
    get:
      operationId: getUser
      parameters:
      - explode: false
        in: path
        name: userId
        required: true
        schema:
          type: integer
        style: simple
      responses:
        200:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
          description: 200 response
        default:
          description: Error response
      tags:
      - users
components:
  schemas:
    UserResponse:
      description: ユーザーレスポンス
      properties:
        user:
          $ref: '#/components/schemas/User'
      required:
      - user
      type: object
    User:
      description: ユーザー
      properties:
        userId:
          description: ユーザーID
          example: 1
          type: integer
        name:
          description: ユーザー名
          example: おとよ
          type: string
        blogUrl:
          description: ブログURL
          example: http://alpacat.hatenablog.com/
          format: uri
          type: string
      required:
      - blogUrl
      - name
      - userId
      type: object

どうでしょうか?パッと見ただけでAPI仕様が理解できてしまいますよね。

さらに良いのは、OpenAPIは特定の言語に依存しないので、サーバ側とクライアント側で開発言語が違っていても問題ないということです。

では、この openapi.yaml に基づいたダミーのAPIサーバーを立ててみましょう。

API Sprout を使ってダミーAPIサーバーを立てる

API Sprout の Releases から、最新バージョンをダウンロードし、解凍してできた実行ファイル apisprout をパスの通った場所に配置します。

あとは openapi.yaml を渡して実行するだけです。驚くほど簡単です。

$ apisprout openapi.yaml
🌱 Sprouting Example API on port 8000

ブラウザで http://localhost:8000/users/1 にアクセスしてみましょう。下記のJSONが返ってくるはずです。

{
  user: {
    blogUrl: "http://alpacat.hatenablog.com/",
    name: "おとよ",
    userId: 1
  }
}

たったこれだけで、ダミーAPIサーバーのできあがりです。example に記述した値をダミーの値として返してくれます。

おまけ: openapi.yamlスキーマクラスを自動生成

さらに言うと、普段一緒にお仕事している @upscent さんが openapi.yaml を食わせてスキーマクラス(Ruby)を自動生成してくれる神ツールを作ってくれて、控えめに言って神です。

「すごく便利なのでOSSにしてください」とお願いしてあるので、そのうち公開してくれると思います。