Help us understand the problem. What is going on with this article?

OpenAPI で API スキーマから Elm コードを生成する

More than 1 year has passed since last update.

OpenAPI とは

WEB+DB PRESS Vol.108 で、「スキーマ駆動Web API開発 OpenAPI/GraphQLで仕様からコードもテストも作成」という特集がありました。
OpenAPI の仕様に従って API スキーマ定義を YAML か JSON で書けば、以下をサポートしてくれます。

  • スキーマから API サーバ・クライアント両方のコード生成
  • スキーマを読み込んで実装が仕様を満たしているかテストできる
  • スキーマからスタブサーバ生成

スキーマからコードを生成する OpenAPI Generator は、API クライアントとして Elm コード(0.19)の出力に対応していました。
Elm で作るアプリケーションにおいて、外部との境界周辺でバグが起きやすいため、そこを補強する手段としてもとても魅力的に見えます。
さっそく試してみました。

1. スキーマを作る

適当に探した API https://thecatapi.com/ をサンプルに使います。
https://api.thecatapi.com/v1/images/search
ランダムで猫の画像 URL を一つ返します。
Screenshot 2018-12-25 22.44.29.png

スキーマのエディター https://editor.swagger.io/ で以下のように書きます。

openapi.yaml
openapi: 3.0.2
info:
  title: TheCatApi
  version: 1.0.0
servers: 
  - url: https://api.thecatapi.com
    description: server
paths:
  /v1/images/search:
    get:
      description: Get random
      operationId: getRandom
      responses:
        '200':
          description: Get random
          $ref: '#/components/schemas/Images'
components:
  schemas:
    Images:
      type: array
      items:
        $ref: '#/components/schemas/Image'
    Image:
      type: object
      properties:
        id:
          type: string
        url:
          type: string

エディター上で定義にエラーが無いことを確認し、[Save as YAML] で YAML ファイルをダウンロードできます。以降ダウンロードしたファイルを openapi.yaml とします。

2. Elm コードを生成する

OpenAPI Generator を使います。
特集では Docker を使用していましたが、Mac なら Homebrew でインストールすることもできます。

$ brew install openapi-generator
$ openapi-generator generate -i openapi.yaml -g elm -o elm-open-api-test

これで以下のように Elm コードが出力されます。

Screenshot 2018-12-25 21.54.20.png

内容としては、モデルと HTTP リクエストのコードがメインです。Main.elm では特に何もしていませんでした。以下が生成されたコードです。

モデル

src/Data/Image.elm
module Data.Image exposing (Image, decoder, encoder)

import Dict exposing (Dict)
import Json.Decode as Decode exposing (Decoder)
import Json.Decode.Pipeline exposing (optional, required)
import Json.Encode as Encode


type alias Image =
    { id : Maybe (String)
    , url : Maybe (String)
    }


decoder : Decoder Image
decoder =
    Decode.succeed Image
        |> optional "id" (Decode.nullable Decode.string) Nothing
        |> optional "url" (Decode.nullable Decode.string) Nothing



encoder : Image -> Encode.Value
encoder model =
    Encode.object
        [ ( "id", Maybe.withDefault Encode.null (Maybe.map Encode.string model.id) )
        , ( "url", Maybe.withDefault Encode.null (Maybe.map Encode.string model.url) )

        ]

HTTP リクエスト

src/Request/Default.elm
module Request.Default exposing (getRandom)

import Dict
import Http
import Json.Decode as Decode


basePath : String
basePath =
    "https://api.thecatapi.com"


{-| Get random
-}
getRandom : Http.Request ()
getRandom =
    { method = "GET"
    , url = basePath ++ "/v1/images/search"
    , headers = []
    , body = Http.emptyBody
    , expect = Http.expectStringResponse (\_ -> Ok ())
    , timeout = Just 30000
    , withCredentials = False
    }
        |> Http.request

スキーマで operationId として定義した名前がリクエスト関数名になるようです。

まとめ

コードを残しておきます。生成されたコードにちょっと書き足して、画像を画面に表示するようにしてあります。
https://github.com/kawausokun/elm-open-api-test

OpenAPI を使った開発の実践を WEB+DB PRESS に詳しく書いてあるので、興味がある方は読んでみてはどうでしょうか。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away