
OpenAPIで可変レスポンスを定義する方法とGoでの実装例
はじめに
こんにちは。テクノロジーセクションの保坂です。
現在弊社が開発・運営しているTECH PORTALの新機能開発において、APIのレスポンスを柔軟に変更しなければならない場面がありました。
通常OpenAPIではレスポンスの型を明確に定義しますが、今回は「カスタム属性」のようなデータを扱う必要があり、同じプロパティに様々な型を返却する必要がありました。 この記事では、OpenAPIで可変なレスポンスを定義する方法と、自動生成されたGoコードをどのように扱ったかを紹介します。
前提
TECH PORTALでは、OpenAPIを利用してAPI仕様を管理しています。
また、oapi-codegenを使用してOpenAPI定義からサーバーのインターフェースや返却する際に使う構造体の一部を自動生成しており、API仕様と実装の乖離を防ぐ運用を取っています。
そのため、新しいAPIを追加する際は、
OpenAPIにスキーマを定義する
バックエンドのコードを自動生成する
生成された型を利用して実装する
という流れで開発を進めています。
今回の課題
新機能では、追加開発を行うことなく、柔軟に設定項目を追加・変更できる仕組みが必要でした。
設定項目には、タイトルのような単純な文字列を持つものや、リンクの表示名と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」を利用した事例を紹介しました。
コードを自動生成していることもあり、アプリケーション内部の型とレスポンスの型の変換に苦労しました。
同様に「レスポンスの型がケースによって変わる」という要件に遭遇した際の参考になれば幸いです。
ーーーーーーーーーーーーーーーーーーーーーーーー
エンジニア採用強化中です!
テックオーシャンではエンジニア採用を強化中です!ご興味がある方は、ぜひこちらからアクセスお願いします!