概要

OpenAPI(Swagger)でAPIのスキーマ定義をyamlで書くスキーマ駆動開発を試みました。

oapi-codegenを使えばyamlファイルに記述したOpenAPIのスキーマ定義を基に、Go言語の構造体やecho向けにルーティングも自動生成できるので便利です。しかしながら、自動生成されたコードのechoルーティングは個別のエンドポイントにミドルウェアを設定することが難しい状態です。

そこで、oapi-codegenが自動生成したコードを活用しつつ、手動でルーティングを実装し、手動実装した部分に漏れや間違いがないようにOpenAPIのスキーマ定義と比較する単体テストを記述することでスキーマ駆動開発を試みました。

この記事で書くこと・やること

oapi-codegenを使ってOpenAPIスキーマ定義からGo言語の構造体、echo用サーバのコードを生成する
ミドルウェア設定のために、手動でルーティングするコードを実装する
手動で書いたルーティングに漏れや間違いがないかスキーマ定義と比較する単体テストを書く

手順

1. oapi-codgenの準備

まだoapi-codegenが準備出来ていなければ下記コマンドでインストールします。

go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest

2. OpenAPIのyamlを記述します。

YAML記述の詳細は省略しますが、下記のようなyamlを書くものとします。

openapi-bundle.yaml

openapi: 3.0.0
info:
  title: API
  description: サンプルAPI
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: ローカル開発環境
paths:
  /auth/sign_up:
    post:
      operationId: SignUp
      summary: アカウント作成
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                myId:
                  type: string
                  description: 取得したいMyIDを指定します。
                  x-oapi-codegen-extra-tags:
                    validate: required
                password:
                  type: string
                  x-oapi-codegen-extra-tags:
                    validate: required
                isAdmin:
                  type: boolean
              required:
                - myId
                - password
                - isAdmin
      responses:
        '200':
          description: アカウント作成に成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  myId:
                    type: string
                required:
                  - myId
        '400':
          description: リクエストに不備がある
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/sign_in:
    post:
      operationId: SignIn
      summary: サインインします。
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInResponse'
      responses:
        '200':
          description: サインイン成功
          content: {}
        '401':
          description: サインイン失敗
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /auth/sign_out:
    post:
      operationId: signOut
      summary: サインアウトします。
      security:
        - cookieAuth: []
      responses:
        '200':
          description: サインアウト
          content: {}
        '401':
          description: 未サインイン
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /photos/{photoId}:
    get:
      operationId: getPhoto
      summary: 写真情報を取得します。
      security:
        - cookieAuth: []
      parameters:
        - name: photoId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: 写真情報
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPhotoResponse'
        '404':
          description: 見つからなかった場合
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /photos:
    get:
      operationId: getPhotos
      summary: 写真一覧を取得します。
      security:
        - cookieAuth: []
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
        - name: offset
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: 写真情報
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetPhotoListResponse'
        '404':
          description: 見つからなかった場合
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: session
  schemas:
    ErrorResponse:
      type: object
      description: エラーレスポンス
      properties:
        statusCode:
          type: integer
          description: HTTPステータスコード
        errorCode:
          type: string
          description: APIが定義するエラーコード
        errorMessage:
          type: string
          description: システムエラーメッセージ詳細
      required:
        - statusCode
        - errorCode
    SignInResponse:
      type: object
      properties:
        myId:
          type: string
          x-oapi-codegen-extra-tags:
            validate: required
        password:
          type: string
          x-oapi-codegen-extra-tags:
            validate: required
      required:
        - myId
        - password
    GetPhotoListResponse:
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/GetPhotoListItem'
        total:
          type: integer
      required:
        - items
        - total
    GetPhotoListItem:
      properties:
        photoId:
          type: integer
      required:
        - photoId
    GetPhotoResponse:
      properties:
        photoId:
          type: integer
        photoName:
          type: string
      required:
        - photoId
        - photoName

3. oapi-codegenでGo言語コードの生成

下記のような設定ファイルを作成してoapi-codegenを実行します。

oapi-codegen.yaml

package: schema
generate:
  - models
  - echo-server
# ↓ 出力先を指定します。
output: interfaces/http/schema/schema.gen.go

# コード生成：
# -configに設定ファイルを指定、そしてOpenAPIのyamlファイルを指定
oapi-codegen -config ./oapi-codegen.yaml ./openapi-bundle.yaml

Go言語のコードが自動生成されます。設定ファイルにecho-serverも指定したのでecho向けのコードも下記のように記述されています。ServerInterfaceでは実装すべきハンドラ関数が定義されています。またルーティング処理も記述されていますが、個別にミドルウェアを設定することが難しい状態になっています。

interfaces/http/schema/schema.gen.go

// ~~ 省略

// ServerInterface represents all server handlers.
type ServerInterface interface {
	// サインインします。
	// (POST /auth/sign_in)
	SignIn(ctx echo.Context) error
	// サインアウトします。
	// (POST /auth/sign_out)
	SignOut(ctx echo.Context) error
	// アカウント作成
	// (POST /auth/sign_up)
	SignUp(ctx echo.Context) error

	// 写真一覧を取得します。
	// (GET /photos)
	GetPhotos(ctx echo.Context, params GetPhotosParams) error
	// 写真情報を取得します。
	// (GET /photos/{photoId})
	GetPhoto(ctx echo.Context, photoId int) error
}

// ~~ 省略

// RegisterHandlers adds each server route to the EchoRouter.
func RegisterHandlers(router EchoRouter, si ServerInterface) {
	RegisterHandlersWithBaseURL(router, si, "")
}

// Registers handlers, and prepends BaseURL to the paths, so that the paths
// can be served under a prefix.
func RegisterHandlersWithBaseURL(router EchoRouter, si ServerInterface, baseURL string) {

	wrapper := ServerInterfaceWrapper{
		Handler: si,
	}

	router.POST(baseURL+"/auth/sign_in", wrapper.SignIn)
	router.POST(baseURL+"/auth/sign_out", wrapper.SignOut)
	router.POST(baseURL+"/auth/sign_up", wrapper.SignUp)
	router.GET(baseURL+"/photos", wrapper.GetPhotos)
	router.GET(baseURL+"/photos/:photoId", wrapper.GetPhoto)
}

4. ルーティング処理を手動実装

本来ならば、自動生成された RegisterHandlersやRegisterHandlersWithBaseURLをそのまま利用できるのが理想ですが、エンドポイントごとに個別にミドルウェアを設定したい場合は利用できません。そこで諦めてルーティング処理だけは自前で手動実装します。

下記は（現時点ではほとんど同じですが）自動生成のルーティング処理を元に手動で記述したルーティング処理です。一部のエンドポイントは middlewares.AuthUserのようにミドルウェアを設定しています。

interfaces/http/route/router.go

func Route(e schema.EchoRouter, si schema.ServerInterface) {
	w := schema.ServerInterfaceWrapper{
		Handler: si,
	}

	e.POST("/auth/sign_up", w.SignUp)
	e.POST("/auth/sign_in", w.SignIn)
	e.POST("/auth/sign_out", w.SignOut, middelwares.AuthUser)
	e.GET("/photos", w.GetPhotos, middelwares.AuthUser)
	e.GET("/photos/:photoId", w.GetPhoto, middelwares.AuthUser)
}

一応、これで完成ではあります。自動生成されたルーティング処理が使えなかったので代わりに手動で実装しました。

5. 漏れや間違いが無いか単体テストを書く

上記までで処理自体の実装は完了しているのですが、せっかくスキーマ駆動開発を試みたのにルーティング処理を手動で記述して漏れや間違いがおこりえます。

そこで、次のような単体テストを書くことで、yamlで定義したOpenAPIのスキーマ定義と手動記述したルーティング処理が一致しているかを担保します。

これは、手動記述したルーティング関数でセットされたエンドポイントが、OpenAPIのyamlファイルを読み込んで定義されているエンドポイントと一致しているか担保する単体テストです。メソッドとパスに誤りや漏れがないかをチェックします。

interfaces/http/router/router_test.go

package routers

import (
	"context"
	"regexp"
	"strings"
	"testing"
	"github.com/stretchr/testify/assert"
	"github.com/getkin/kin-openapi/openapi3"
	"github.com/labstack/echo/v4"
)

func TestApiRouter_route(t *testing.T) {
	loadOpenAPISpec := func(t *testing.T, path string) *openapi3.T {
		loader := openapi3.NewLoader()
		doc, err := loader.LoadFromFile(path)
		assert.NoError(t, err, "failed to load OpenAPI")
		err = doc.Validate(context.Background())
		assert.NoError(t, err, "failed to validate OpenAPI")
		return doc
	}

	getRegisteredRoutes := func(e *echo.Echo) map[string]string {
		routes := make(map[string]string) // key: METHOD PATH, value: name
		for _, r := range e.Routes() {
			key := r.Method + " " + r.Path
			routes[key] = r.Name
		}
		return routes
	}

	// OpenAPIのパスパラメータ`{photoId}`形式をechoのパスパラメータ`:photoId`に変換する。
	openAPIPathToEchoPath := func(path string) string {
		re := regexp.MustCompile(`\{([^}]+)\}`)
		return re.ReplaceAllString(path, `:$1`)
	}

	t.Run("ルーティングのパスがOpenAPI定義と一致しているかテスト", func(t *testing.T) {
		ctrl := gomock.NewController(t)
		defer ctrl.Finish()

		e := echo.New()
        h := &ServerHandler{} // ServerInterfaceの実装をセット（モックでもOK）
		Route(e, h)

		actual := getRegisteredRoutes(e)
		doc := loadOpenAPISpec(t, "/path/to/openapi-bundle.yaml")

		for path, pathItem := range doc.Paths.Map() {
			for method, operation := range pathItem.Operations() {
				method = strings.ToUpper(method)
				echoPath := openAPIPathToEchoPath(path)
				key := method + " " + echoPath
				if _, ok := actual[key]; !ok {
					t.Errorf("Missing route implementation: %s %s (operationId: %s)", method, path, operation.OperationID)
				}
			}
		}

	})
}

まとめ

oapi-codegenでOpenAPIのスキーマ定義からGo言語のコードを自動生成しました。しかしながら、自動生成されたルーティング処理はミドルウェアを個別に指定できなかったため、ルーティング処理を手動で実装しました。そして、手動での記述に漏れや間違いがないかをチェックする単体テストを書きました。

付録

他のやり方

他の方も、oapi-codegenがミドルウェアをエンドポイントごとに設定できないルーティングコードを生成するので、ミドルウェア設定に試行錯誤されているようでした。