メインコンテンツへスキップ
見出し画像

OpenAPIで可変レスポンスを定義する方法とGoでの実装例

    はじめに

    こんにちは。テクノロジーセクションの保坂です。

    現在弊社が開発・運営しているTECH PORTALの新機能開発において、APIのレスポンスを柔軟に変更しなければならない場面がありました。

    通常OpenAPIではレスポンスの型を明確に定義しますが、今回は「カスタム属性」のようなデータを扱う必要があり、同じプロパティに様々な型を返却する必要がありました。 この記事では、OpenAPIで可変なレスポンスを定義する方法と、自動生成されたGoコードをどのように扱ったかを紹介します。

    前提

    TECH PORTALでは、OpenAPIを利用してAPI仕様を管理しています。

    また、oapi-codegenを使用してOpenAPI定義からサーバーのインターフェースや返却する際に使う構造体の一部を自動生成しており、API仕様と実装の乖離を防ぐ運用を取っています。

    そのため、新しいAPIを追加する際は、

    1. OpenAPIにスキーマを定義する

    2. バックエンドのコードを自動生成する

    3. 生成された型を利用して実装する

    という流れで開発を進めています。

    今回の課題

    新機能では、追加開発を行うことなく、柔軟に設定項目を追加・変更できる仕組みが必要でした。

    設定項目には、タイトルのような単純な文字列を持つものや、リンクの表示名とURLをセットで持つものなど、複数の形式が存在します。

    そのため設定値はDB上でJSON形式として保持しており、APIでは保存されている値の構造に応じて適切な型として返却する必要がありました。

    このような背景から、同じエンドポイントで以下のような異なる形式のレスポンスを返却するケースが存在します。

    文字列を返すケース

    {
        "id": "test-object1",
        "data": "文字列"
    }

    オブジェクトを返すケース

    {
        "id": "test-object2",
        "data": {
            "name": "オブジェクト",
            "value": "値"
        }
    }

    文字列の配列を返すケース

    {
        "id": "test-object3",
        "data": [
            "文字列1",
            "文字列2"
        ]
    }

    オブジェクトの配列を返すケース

    {
        "id": "test-object4",
        "data": [
            {"name": "オブジェクト1", "value": "値1"},
            {"name": "オブジェクト2", "value": "値2"}
        ]
    }

    問題となったのは data フィールドです。

    通常であれば「type: string」や「type: object」のように型を固定して定義しますが、今回は返却内容によって型が変化します。

    このようなケースをどのようにOpenAPIで表現するかが課題となりました。

    可変レスポンスの定義方法

    OpenAPIでは oneOf を利用することで、複数の型を指定できます。 さらに、object の場合は「additionalProperties: true」を指定することで、任意のプロパティを許可することができます。

    今回の例では以下のように定義しました。

    components:
      schemas:
        MultiTypeDataString:
          type: string
    
        MultiTypeDataObject:
          type: object
          additionalProperties: true
    
        MultiTypeDataArray:
          type: array
          items:
            oneOf:
              - $ref: '#/components/schemas/MultiTypeDataString'
              - $ref: '#/components/schemas/MultiTypeDataObject'
    
        MultiTypeResponse:
          type: object
          required:
            - id
            - data
          properties:
            id:
              type: string
            data:
              oneOf:
                - $ref: '#/components/schemas/MultiTypeDataString'
                - $ref: '#/components/schemas/MultiTypeDataObject'
                - $ref: '#/components/schemas/MultiTypeDataArray'

    この定義により、data は以下のいずれかの型として扱われます。

    • MultiTypeDataString

    • MultiTypeDataObject

    • MultiTypeDataArray

    String や Array も別のスキーマとして切り出したのには理由があります。 今回使用している oapi-codegen の oneOf では、スキーマ名がついていないと指定された順番に連番で型が生成されます。
    そうなると、どの数字がどの型に対応しているか分かりづらいこと、API定義の編集時に順序を変更してしまいコードに影響が出てしまうことが考えられます。
    そのためスキーマとして分離することでこの問題を解決しています。

    OpenAPIコード生成後の課題

    OpenAPI上では期待通りに表現できましたが、次に問題になったのがコード生成後の型です。
    利用しているコードジェネレーターでは、oneOf が以下のような型として生成されました。

    type MultiTypeDataObject map[string]interface{}
    type MultiTypeDataString string
    
    type MultiTypeResponse {
        id   string
        data MultiTypeResponse_Data
    }
    
    type MultiTypeResponse_Data struct {
        union json.RawMessage
    }
    
    func (t MultiTypeResponse_Data) AsMultiTypeDataObject() (MultiTypeDataObject, error) {
    	var body MultiTypeDataObject
    	err := json.Unmarshal(t.union, &body)
    	return body, err
    }
    func (t *MultiTypeResponse_Data) FromMultiTypeDataObject(v MultiTypeDataObject) error {
    	b, err := json.Marshal(v)
    	t.union = b
    	return err
    }
    // MultiTypeDataString / MultiTypeDataArray も同様

    MultiTypeDataArray については、さらに中の構造がマッピングできるようItemsの部分も生成されていました。

    type MultiTypeDataArray = []MultiTypeDataArray_Item
    
    type MultiTypeDataArray_Item struct {
    	union json.RawMessage
    }
    
    func (t MultiTypeDataArray_Item) AsMultiTypeDataObject() (MultiTypeDataObject, error) {
    	var body MultiTypeDataObject
    	err := json.Unmarshal(t.union, &body)
    	return body, err
    }
    
    func (t *MultiTypeDataArray_Item) FromMultiTypeDataObject(v MultiTypeDataObject) error {
    	b, err := json.Marshal(v)
    	t.union = b
    	return err
    }
    
    // MultiTypeDataString も同様

    内部的には JSON データをそのまま保持するラッパー型になっており、そのままでは文字列やオブジェクトとして利用できません。

    そのため、利用する側で型変換を行う必要がありました。

    Goで型変換する方法

    アプリケーション内部では、以下のような構造体でデータを持っているため自動生成された MultiTypeDataString などの最適な型に変換する必要があります。

    type Model struct {
        Id   string
        Data any
    }

    今回は、anyの型から判定してどのレスポンス用の構造体に変換するかを判定しました。

    func ConvertToResponse(model Model) (MultiTypeResponse, error) {
        var data MultiTypeResponse_Data
        var err error
    
        switch val := model.Data.(type) {
            case string:
                err = data.FromMultiTypeDataString(val)
            case map[string]any:
                err = data.FromMultiTypeDataObject(val)
            case []string:
                data, err = toMultiTypeDataStringArray(val)
            case []any:
                data, err = toMultiTypeDataObjectArray(val)
            default:
                err = errors.New("failed to convert response data")
        }
        if err != nil {
            return MultiTypeResponse{}, err
        }
    
        return MultiTypeResponse{
            Id:   model.Id,
            Data: data,
        }, nil
    }
    
    // string 配列専用の変換メソッド
    func toMultiTypeDataStringArray(val []string) (MultiTypeResponse_Data, error) {
        var value MultiTypeResponse_Data
        var err error
        var items = make([]MultiTypeDataArray_Item, 0, len(val))
    
        for _, str := range val {
            var item MultiTypeDataArray_Item
            err = item.FromMultiTypeDataString(str)
            if err != nil {
                return value, errors.New("failed to convert string array")
            }
            items = append(items, item)
        }
        err = value.FromMultiTypeDataArray(items)
        if err != nil {
            return value, errors.New("failed to convert string array")
        }
    
        return value, nil
    }
    
    // object 配列専用の変換メソッド
    func toMultiTypeDataObjectArray(val []any) (MultiTypeResponse_Data, error) {
        var value MultiTypeResponse_Data
        var err error
        var items = make([]MultiTypeDataArray_Item, 0, len(val))
    
        for _, obj := range val {
            var item MultiTypeDataArray_Item
            objMap, ok := obj.(map[string]any)
            if !ok {
                return value, errors.New("failed to convert object array")
            }
            err = item.FromMultiTypeDataObject(objMap)
            if err != nil {
                return value, errors.New("failed to convert object array")
            }
            items = append(items, item)
        }
        err = value.FromMultiTypeDataArray(items)
        if err != nil {
            return value, errors.New("failed to convert object array")
        }
    
        return value, nil
    }

    配列を変換しなければならないパターンでは特に工夫をして内部構造まで変換して返却できる専用のメソッドを作成しています。

    最後に

    今回は、OpenAPIで可変なレスポンスを定義する方法として「oneOf」と「additionalProperties」を利用した事例を紹介しました。
    コードを自動生成していることもあり、アプリケーション内部の型とレスポンスの型の変換に苦労しました。

    同様に「レスポンスの型がケースによって変わる」という要件に遭遇した際の参考になれば幸いです。
    ーーーーーーーーーーーーーーーーーーーーーーーー
    エンジニア採用強化中です!

    テックオーシャンではエンジニア採用を強化中です!ご興味がある方は、ぜひこちらからアクセスお願いします!

     
     
    テックオーシャンは「人と組織の可能性を最大化し、豊かな暮らしを社会をつくる」をビジョンに掲げ、 「TECH人材」「企業」「私たち」の可能性を信じ、それぞれが持つ力を最大限に引き出すことで、豊かな社会づくりに取り組みます。 https://techocean.co.jp/

    あなたへのおすすめ