Closed2021/11/30にクローズ3

【Go】oapi-codegenメモ

OpenAPI

oapicodegen

yagi_eng

これ

openapi.ymlから構造体やルーティング、簡単なバリデーションを自動生成できる優れもの
https://github.com/deepmap/oapi-codegen

参考

基本的に以下の記事を参考にすればOK
細かい点のみこのスクラップで補足

構造体の自動生成

こんな感じで自動生成される

// Type definition for component schema "Error"
type Error struct {
    Code    int32  `json:"code"`
    Message string `json:"message"`
}

// Type definition for component schema "NewPet"
type NewPet struct {
    Name string  `json:"name"`
    Tag  *string `json:"tag,omitempty"`
}

// Type definition for component schema "Pet"
type Pet struct {
    // Embedded struct due to allOf(#/components/schemas/NewPet)
    NewPet
    // Embedded fields due to inline allOf schema
    Id int64 `json:"id"`
}

// Type definition for component schema "Pets"
type Pets []Pet

controller相当部分の自動生成

以下のようなinterfaceが自動生成されるので、これを実装していく

type ServerInterface interface {
    //  (GET /pets)
    FindPets(ctx echo.Context, params FindPetsParams) error
    //  (POST /pets)
    AddPet(ctx echo.Context) error
    //  (DELETE /pets/{id})
    DeletePet(ctx echo.Context, id int64) error
    //  (GET /pets/{id})
    FindPetById(ctx echo.Context, id int64) error
}

notes

上記interfaceを実装するメソッドの返り値
- c.JSON (error型)などをreturnすればOK
- つまり、responseのbindはしてくれない
openapi.ymlのnumber型プロパティはformat: doubleを指定すると、float64型になる
- formatを指定しないと、float32型になる
openapi.ymlでnumber型にrequierdを指定した場合、0は弾かれるか？
- 弾かれない
- https://github.com/go-playground/validator だと弾かれるから調べてみた
バリデーションはrequierdと型チェックくらいしかしてくれず、他の細かいバリデーションは自分で実装する必要ある
- openapi.ymlのプロパティにminimun: 0などを指定できるが、oapi-codegenによる自動生成ではそれをコード化する仕組みはない
  - https://swagger.io/docs/specification/data-models/data-types/#numbers
- middleware.OapiRequestValidator(swagger)を使うとできる？
  - https://github.com/deepmap/oapi-codegen/blob/master/pkg/middleware/oapi_validate.go
  - できるとの情報はあり
    - https://future-architect.github.io/articles/20200701/
      - Echo だと middleware をいれれば Body のバリデーションエラーも見れる
  - このmiddlewareは内部的に以下のライブラリを呼んでいた
    - https://github.com/getkin/kin-openapi
自動生成されたバリデーション部分は、エラーを返す時にstring型でエラー内容を返している
自動生成コードによるparameterのbind
- GETの場合（queryparameter, pathparameterの場合）してくれる
- POST/PUTの場合(request bodyの場合)してくれない
  - echo.Context.Bindで自前でbindする必要がある
  - https://github.com/deepmap/oapi-codegen/blob/32316b9c067a927466db3d16958f290cba4841b8/examples/petstore-expanded/echo/api/petstore.go#L83
  - バリデーションもおそらく自前？自前だと自動生成されたrequest用の構造体にバリデーションを組み込む必要があり、実用的ではない。middleware.OapiRequestValidator(swagger)が解決してくれるか？
oapi-codegenについて、クライアント（HTTPサーバにリクエストを送るやつ）も自動生成してくれる
- APIの結合テストとかに使えそう

yagi_eng

OapiRequestValidator調査

openapi.ymlを基にバリデーションをしてくれる
GETと同じ内容をバリデーションしてくれる
- requierdと型チェックはしてくれる
minimum, lengthなどはチェックしてくれない
POST/PUTメソッドにおいて、requestBodyの構造体タグにはqueryではなくjsonを使う必要がある
- 自動生成されたコードではjsonタグを使っているので特に気にする必要なし
kin-openapiについて、リポジトリやコードを読み込めばもっと色々機能ありそう

yagi_eng

で生成されるコードはなんか微妙。Go用の方が使い勝手良い

GETのpath/query paramはcontroller内部で受け取りされる。構造体は生成されない

// GetXXX - Get XXX
func (c *XXXApiController) GetXXX(w http.ResponseWriter, r *http.Request) {
	params := mux.Vars(r)
	idParam, err := parseInt32Parameter(params["id"], true)
	if err != nil {
		c.errorHandler(w, r, &ParsingError{Err: err}, nil)
		return
	}

	result, err := c.service.GetXXX(r.Context(), idParam)
	// If an error occurred, encode the error with the status code
	if err != nil {
		c.errorHandler(w, r, err, &result)
		return
	}
	// If no error, encode the body and the result code
	EncodeJSONResponse(result.Body, &result.Code, w)

}

オプションの設定がCLIのhelpと以下ドキュメントで乖離してる

openapi-generator-cli config-help -g go-server


CONFIG OPTIONS

        addResponseHeaders
            To include response headers in ImplResponse (Default: false)

        enumClassPrefix
            Prefix enum with class name (Default: false)

        featureCORS
            Enable Cross-Origin Resource Sharing middleware (Default: false)

        hideGenerationTimestamp
            Hides the generation timestamp when files are generated. (Default: true)

        packageName
            Go package name (convention: lowercase). (Default: openapi)

        packageVersion
            Go package version. (Default: 1.0.0)

        router
            Specify the router which should be used. (Default: mux)
                mux - mux
                chi - chi

        serverPort
            The network port the generated server binds to (Default: 8080)

        sourceFolder
            source folder for generated code (Default: go)

このスクラップは2021/11/30にクローズされました