OpenAPI에서 API 스키마에서 Elm 코드 생성

OpenAPI란?

WEB+DB PRESS Vol.108 에서, 「스키마 구동 Web API 개발 OpenAPI/GraphQL로 사양으로부터 코드도 테스트도 작성」이라고 하는 특집이 있었습니다.
OpenAPI 사양에 따라 API 스키마 정의를 YAML 또는 JSON으로 작성하면 다음을 지원할 수 있습니다.

스키마에서 API 서버 클라이언트에 대한 코드 생성

스키마를로드하여 구현이 사양을 충족하는지 테스트 할 수 있습니다

스키마에서 스텁 서버 생성

스키마에서 코드를 생성하는 OpenAPI Generator는 API 클라이언트로서 Elm 코드(0.19)의 출력을 지원했습니다.
Elm으로 만드는 어플리케이션에서 외부와의 경계 주변에서 버그가 일어나기 쉽기 때문에 거기를 보강하는 수단으로서도 매우 매력적으로 보입니다.
즉시 시도해 보았습니다.

1. 스키마 만들기

적절한 APIhtps : /// ぇ카타피. 코m/를 샘플에 사용합니다.
htps : // 아피. 테카타피. 코 m/v1/메게 s/세아 rch
무작위로 고양이의 이미지 URL을 하나 반환합니다.


스키마 편집기htps : // 에아와 r. 슈게 r. 이오/에서 다음을 작성합니다.

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 코드가 출력됩니다.



내용은 모델과 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로 정의한 이름이 요청 함수 이름이 되는 것 같습니다.

요약

코드를 남겨 둡니다. 생성된 코드에 조금 써서 이미지를 화면에 표시하도록 합니다.
htps : // 기주 b. 코 m / 카와 우소 군 / 에 lm- 오펜 - 아피 st

OpenAPI를 사용한 개발 실습을 WEB+DB PRESS에 자세하게 쓰고 있으므로, 흥미가 있는 분은 읽어 보면 어떨까요.