ikorihn Digitalgarden

Search

SearchSearch

Recent Notes

OpenAPIとGoでリクエストのバリデーションをする

2023-01-057 min read

いつもoapi-codegenでopenapi.yamlからGoのコードを生成するようにしている。 oapi-codegenの使い方については下記参照

OpenAPIでGoとTypeScriptのコード生成

OpenAPI仕様書からGoの構造体を作る

OpenAPIでパラメータに制約をつける

OpenAPI Documentでは、JSON Schema の定義に従って schema に制約を書くことができる。 OpenAPI Specification - Version 3.0.3 | Swagger draft-wright-json-schema-validation-00

次のように pattern や format 、maxLength などが定義できる。

openapi.yaml

paths:
  /hello:
    get:
      summary: Hello
      operationId: hello
      parameters:
        - name: id
          in: query
          description: user id
          required: true
          schema:
            type: string
            pattern: "^[0-9A-F]+$"
        - name: updated
          in: query
          schema:
            type: string
            format: date-time

oapi-codegenを使えば、 schema に書いた制約をもとにリクエストのバリデーションを行うことができる。

以下はEchoの場合

package main
 
import (
	"my-application/oapigen"
 
	oapiMiddleware "github.com/deepmap/oapi-codegen/pkg/middleware"
	"github.com/getkin/kin-openapi/openapi3"
	"github.com/labstack/echo/v4"
)
 
func main() {
	e := echo.New()
 
	// oapi-codegenで生成したコードにあるGetSwagger()でopenapi specを取得
	swagger, err := oapigen.GetSwagger()
	if err != nil {
		panic(err)
	}
	// ホストの検証が必要でなければnilにしておく
	swagger.Servers = nil
	// middlewareにValidatorをセットすることでリクエストの検証が行われる
	e.Use(oapiMiddleware.OapiRequestValidator(swagger))
 
	// 独自のformatを定義したい場合はこのようにする
	openapi3.DefineStringFormat("custom-date", `^[0-9]{4}-(0[0-9]|10|11|12)-([0-2][0-9]|30|31)T[0-9]{2}:[0-9]{2}:[0-9]{2}$`)
 
 
}

OpenAPIスキーマ駆動開発におけるoapi-codegenを用いたリクエストバリデーション - HRBrain Blog こちらに書いてあるとおり、一通りのバリデーションはできるようになっている

middlewareのソースはこちら https://github.com/deepmap/oapi-codegen/blob/ab90f1927bc5ec3e29af216d4298fbb4780ae36d/pkg/middleware/oapi_validate.go#L58

別ライブラリと組み合わせる

https://github.com/go-ozzo/ozzo-validation や https://github.com/go-playground/validator と組み合わせて複雑なバリデーションをしたい場合

x-oapi-codegen-extra-tags を書くことで任意のstruct tagをつけることができるので、タグベースのバリデーションはこれで行える バリデーションの種類はこれ go-playground/validator リクエストパラメータ向けValidationパターンまとめ - Qiita

paths:
  /hello:
    get:
      summary: Hello
      operationId: hello
      parameters:
        - name: sort-by
          in: query
          description: How to sort items
          required: false
          schema:
            type: string
          x-oapi-codegen-extra-tags:
            validate: len=5
        - name: datetime
          in: query
          schema:
            type: string
          x-oapi-codegen-extra-tags:
            validate: datetime_without_timezone

Echo + go-playground/validator

import (
	"my-application/openapi"
 
	"github.com/go-playground/validator/v10"
)
 
func main() {
	e := echo.New()
 
	swagger, err := openapi.GetSwagger()
	if err != nil {
		panic(err)
	}
	swagger.Servers = nil
	openapi.RegisterHandlers(e, handler{})
 
	// registor validator
	validate := validator.New()
	validate.RegisterValidation("datetime_without_timezone", validateDatetimeWithoutTimezone)
	e.Validator = &CustomValidator{validate: validate}
 
}
 
type CustomValidator struct {
	validate *validator.Validate
}
 
func (cv *CustomValidator) Validate(i interface{}) error {
	if err := cv.validate.Struct(i); err != nil {
		return echo.NewHTTPError(http.StatusBadRequest, err.Error())
	}
	return nil
}
 
func validateDatetimeWithoutTimezone(fl validator.FieldLevel) bool {
	date := fl.Field().String()
	_, err := time.Parse("2006-01-02T15:04:05", date)
	return err == nil
}
 
type handler struct {}
 
func (h handler) Hello(ec echo.Context, params openapi.HelloParams) error {
	if err := ec.Validate(params); err != nil {
		return err
	}
	return ec.String(http.StatusOK, fmt.Printf("Hello, %s", params.Name))
}

validatorのエラーメッセージをカスタムしたい

[golang]Echoでvalidatorのエラーを日本語に変換する方法 | CodeLab How can I define custom error message? · Issue #559 · go-playground/validator

tagに応じたメッセージを作成する、validator.ValidationErrors.Translate で翻訳する(用意された翻訳メッセージ)

package main
 
import (
	"errors"
	"log"
	"net/http"
	"reflect"
	"strings"
	"time"
 
	"github.com/go-playground/locales/ja_JP"
	ut "github.com/go-playground/universal-translator"
	"github.com/go-playground/validator/v10"
	ja_translations "github.com/go-playground/validator/v10/translations/ja"
	"github.com/labstack/echo/v4"
)
 
func main() {
	e := echo.New()
 
	validate := validator.New()
 
	// エラーメッセージに出力するフィールド名をタグから取得する
	validate.RegisterTagNameFunc(func(field reflect.StructField) string {
		fieldName := field.Tag.Get("field_ja")
		if fieldName == "-" {
			return ""
		}
		return fieldName
	})
 
	// 日本語のメッセージを出力する
	japanese := ja_JP.New()
	uni := ut.New(japanese, japanese)
	trans, _ := uni.GetTranslator("ja")
	err := ja_translations.RegisterDefaultTranslations(validate, trans)
	if err != nil {
		log.Fatal(err)
	}
	// メッセージを上書きする場合はこのようにする
	validate.RegisterTranslation("required", trans, func(ut ut.Translator) error {
		return ut.Add("required", "{0} を指定してください", true) // see universal-translator for details
	}, func(ut ut.Translator, fe validator.FieldError) string {
		t, _ := ut.T("required", fe.Field())
		return t
	})
 
	e.Validator = &CustomValidator{validate: validate, trans: trans}
 
}
 
type CustomValidator struct {
	trans    ut.Translator
	validate *validator.Validate
}
 
func (cv *CustomValidator) Validate(i interface{}) error {
	if err := cv.validate.Struct(i); err != nil {
		var ve validator.ValidationErrors
		msg := []string{}
		if errors.As(err, &ve) {
			for _, m := range ve.Translate(cv.trans) {
				msg = append(msg, m)
			}
		}
 
		return echo.NewHTTPError(http.StatusBadRequest, strings.Join(msg, ","))
	}
	return nil
}
 
type Params struct {
	Id *string `form:"id,omitempty" json:"id,omitempty" validate:"required" field_ja:"ユーザID"`
}

⇒ ユーザIDは必須フィールドです というエラーメッセージになる

試す

openapi: "3.1.0"
paths:
  /hello:
    get:
      summary: Sample API
      operationId: hello
      tags:
        - sample
      parameters:
        - name: name
          in: query
          required: true
          schema:
            type: string
            maxLength: 8
            minLength: 4
          description: your name
        - name: id
          in: query
          schema:
            type: string
            pattern: "^\\d{8}$"
          description: your id
        - name: age
          in: query
          schema:
            type: integer
            maximum: 30
            minimum: 10
          description: your name

こんなopenapi.yamlを作って適当なサーバーを立てて、範囲外の値を入力してやるとエラーが返された

localhost:8080/hello?name=alice&age=99

parameter "age" in query has an error: number must be at most 30

日付型のバリデーション

kin-openapiだけだとここで正規表現のみチェックしている https://github.com/getkin/kin-openapi/blob/e7d649f3f7d6ddbaaaed74a7d2f819a82118aab4/openapi3/schema.go#L943 https://github.com/getkin/kin-openapi/blob/e7d649f3f7d6ddbaaaed74a7d2f819a82118aab4/openapi3/schema_formats.go#L94

2022-01-02T15:04:05 みたいな文字列が通るはずと思ったが通らなかった。

oapi-codegen のmiddlewareではここで time.Parse できるかもチェックしているためだった。 https://github.com/deepmap/oapi-codegen/blob/ab90f1927bc5ec3e29af216d4298fbb4780ae36d/pkg/runtime/bindstring.go#L125

そのため独自フォーマットを用意してあげる必要がある。

 
import "github.com/getkin/kin-openapi/openapi3"
 
 
	openapi3.DefineStringFormat("custom-date", `^[0-9]{4}-(0[0-9]|10|11|12)-([0-2][0-9]|30|31)T[0-9]{2}:[0-9]{2}:[0-9]{2}$`)
  /hello:
    get:
      summary: Sample API
      operationId: hello
      tags:
        - admin
      parameters:
        - name: obj
          in: query
          schema:
            type: object
            properties:
              date:
                type: string
                format: date-time
          style: deepObject
          explode: true

再現できた。エラーメッセージのtimeがtimになってる http://localhost:1323/hello?obj[date]=2022-12-21T15:04:05

Invalid format for parameter obj: error assigning value to destination: error assigning field [date]: error parsing tim as RFC3339 or 2006-01-02 time: parsing time "2022-12-21T15:04:05": extra text: "T15:04:05"

Graph View

OpenAPIとGoでリクエストのバリデーションをするOpenAPIでGoとTypeScriptのコード生成OpenAPI仕様書からGoの構造体を作る#Go#OpenAPIoapi-codegenGo mergoを使って複数のyamlやjsonを一つにマージするGoのhttp.Client利用時の注意事項まとめchromedpを使ってGoでChromeを自動操作するAWS LambdaでGoのWebサーバーを動作させるAWS Lambdaでtmpを使うときの注意AWS SAM Goのカスタムランタイム用パッケージをMakefileでビルドするAWS ElasticacheのAuto Discoveryを利用するAthena aws-sdk-go-v2で結果をS3からダウンロードするAthena aws-sdk-go-v2で結果を取得するDynamoDB aws-sdk-go-v2でBatchGetするメモGo 1.22でループ変数の共有が特定のケースでされなくなるGo DynamoDBのコンソールからダウンロードしたCSVをBatchでputするGo EchoサーバーGo GORMでPrepareStmt trueにしたときにメモリリークが発生したGo GORMでSQL実行前後に実行されるHookを登録するGo Ginに入門してみるGo Neovimでtemplateのsyntax highlightを効かせるGo OSのcredential管理を利用するGo Revel入門Go Sentryに送信するGo TCP接続とDNS問い合わせの頻度、それによる実行時間の違いを調査Go checksumの照合についてGo circuit breakerライブラリを試すGo cognitoのjwtを検証するGo echoサーバーのテストGo go-cmpでStructのfieldがfuncの場合に比較するGo gomock を使ったテストGo http clientでコネクション断をテストするGo http.ClientのConnection設定値について調査Go http.ServerのGraceful shutdownGo oapi-codegenでparametersを独自型にバインドするGo reflectパッケージを使ってfuncを実行するGo reflectパッケージを使ってsliceの値を取得するGo reflectパッケージを使って関数名を取得するGo vscode-goでgoimports時にlocalを指定するGo webサーバーをホットリロードするGo ターミナルのプロンプトでpasswordを入力するGo プライベートリポジトリに対してsshを使ってgo getするGo ローカルで開発中のモジュールを別の箇所で読み込ませるGo 並列で一定時間タスクを実行しつづける負荷試験ツールを実装するGo 呼び出し元の関数名を含めてログ出力するGo 複数のLambdaで共通で実行する処理をmiddlewareで書くGo 関数呼び出し元の情報を出力するGoGoでCPU使用率が異常に上がっているときはメモリ使用量を見てGC頻度を調べようGoでJSONの時刻を扱う場合Goでhttpコネクションを再利用されるように書くGoに三項演算子が採用されない理由GoのメトリクスをPrometheusで収集するGoの最新バージョンをインストールするワンライナーHaversineの公式で2地点の距離を求めるHugo relative linkHugo 外部リンクをカードで表示するHugoLambdaでタイムアウトしたときに処理をしたいLocalStack内のLambdaからDynamoDBやSESを実行するときのEndpointLocustとBoomerを使ってGoで負荷試験のスクリプトを書くOpenTelemetry CollectorとJeagerでテレメトリを収集・可視化してみるOpenTelemetry CollectorとOpenObserveでテレメトリを収集・可視化してみるOpenTelemetryをGoのnethttpサーバに実装するTUIでPostman風味のHTTPクライアントを作るaws-sdk-go-v2 でのエラーハンドリングaws-sdk-go-v2を使うgo 1.19アップデート内容go カスタムエラーgo モジュールのタグを別のコミットハッシュにつけ直したらcacheが残っていてパッケージうまく読み込めなかったgo-cmpgo-cmpでカスタムの比較処理を書くgo-installでtools.goを排除go-taskを使ってGo,Echoの環境でホットリロードするgo_contextのタイムアウトとキャンセルgo_httpClientをテストするgo_installgo_jsonにmapをmarshalするgo_mockerygo_testifyを使うgofakeitを使ってランダムなデータを作成するgomplategoでDBに絡むテストをしたいgoでsingletonpver_with_cobraslack-goでSocket modeを使用してSlackに投稿するsqlxとXSAM otelsqlを組み合わせたときにplaceholderが変換されないtviewuber-go_zapのサンプリングについてvegetaをライブラリとして使用して負荷試験をするzap.Loggerでログ出力時にSentryにも出力する緯度経度で2地点間の距離を計算する記事メモ ZOZOTOWNのGo言語におけるマイクロサービス開発の共通規約を守るための取り組みOpenAPI GeneratorOpenAPI yamlを編集するときにSwagger Editorなどを使うOpenAPIOpenAPIのspecからSAMのTemplate.yamlを生成するopenapi-generatorで生成したtypescript-fetchのクライアントにmiddlewareを設定するopenapi-generatorで生成したtypescript-fetchの通信部をカスタマイズするtypescript-openapiKustomizeXPath#Draft#AWS#LambdaAWS LambdaMakeAthenaS3#Athenaaws-sdk-go-v2 Athenaにクエリを投げて結果をページングで受け取るExponential Backoff and Jitter#DynamoDBnvim-treesitter#NeovimJFrog Artifactorycircuit breaker patternHystrix dashboard#vscodeGit fatal detected dubious ownership in repositoryエラー#gitAmazon SNSでSDKを使ってSMSを送信するCloud Native Days in Tokyo 2023Concourse CIを試してみるGo SQLBoilerの使い方Go http ClientにOpenTelemetryを計装するJaegerLuaSnipのpostfixを設定するPulumiVegetadotfilesをchezmoi管理に移行するetcdctlvhsコマンド#Prometheus#HugoQuartzを使ってObsidianを無料で公開してみたQuartz v4でObsidianを公開したQuartz v4アップデートLocalStackを使ってSQS,Lambda,SES構成のメール配信をローカルで実行するLocustPython負荷試験 k6についてJavaScript#loadtestBoomerでイベントを受け取ってcallbackを実行させるOpenTelemetry CollectorPrometheus#OpenTelemetryOpenTelemetry Collector Builder(ocb)で自前のCollectorを作るOpenTelemetryをGoのechoサーバーで収集するOpenObserveXDG_BASE_DIRECTORY#terminalAWS#unittest#SlackGo sql.DB にOpenTelemetryのSpanを追加する#articleStep CIを使ってAPIのシナリオテストを行うSAM#TypeScript

Backlinks

  • No backlinks found

Archive