🚶♂️
stepCIのOpenAPI定義インポートを試してみた
概要
OpenAPI定義書ドリブンで開発を進めるケースもあり、stepCIワークフローとgoのechoのコードを自動生成して試したメモ。
やってみた
OpenAPI定義の作成
簡単なGETとPOSTの定義を作成します。
公式の下記記載を参考に、バージョンは3.0.3で作成します。
WARNING
Only OpenAPI 3.0 and higher is supported. Prepare your OpenAPI spec before > running the command. Add request and response examples, default values and > specify required params
https://docs.stepci.com/import/openapi.html
openapi.yml
version: "1.0"
name: step-ci-testing
config:
http:
baseURL: http://localhost:8888
tests:
morphs:
steps:
- id: getMorphs
http:
url: /morphs
method: GET
check:
status: 200
schema:
$ref: "#/components/schemas/Morphs"
- id: postMorph
http:
url: /morphs
method: POST
headers:
Content-Type: application/json
accept: application/json
json:
name: sed magna in
check:
status: 200
schema:
$ref: "#/components/schemas/Morph"
- id: getMorphById
http:
url: /morphs/1
method: GET
check:
status: 200
schema:
$ref: "#/components/schemas/Morph"
components:
schemas:
Morph:
allOf:
- type: object
required:
- id
properties:
id:
type: integer
example: 1
- $ref: "#/components/schemas/NewMorph"
NewMorph:
type: object
required:
- name
properties:
name:
type: string
example: Normal
Morphs:
type: array
items:
$ref: "#/components/schemas/Morph"
Id:
type: integer
example: 1
API実装
oapi-codegenを利用します。
$ go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest
oapi-codegenを実行するgo generate用のファイルgen/gen.goを作成します。
gen/gen.go
//go:generate oapi-codegen -package oapi -include-tags "morphs" -o ../oapi/morphs.gen.go ../openapi.yml
package main
func main() {}
実行してmorphs.gen.goを生成します。
$ go generate ./gen
生成コードを参照しmain.goを実装します。
JSONファイルをDBとして読み書きするAPIとして簡易に実装します。
main.go
package main
import (
"encoding/json"
"io/ioutil"
"net/http"
"os"
"github.com/labstack/echo/v4"
"step-ci-testing/oapi"
)
// ServerInterfaceを満たすよう実装
type controller struct {}
func (c controller) GetMorphs(ctx echo.Context) error {
morphs := readData("data.json")
return ctx.JSON(http.StatusOK, &morphs)
}
func (c controller) PostMorph(ctx echo.Context) error {
newMorph := new(oapi.NewMorph)
ctx.Bind(newMorph)
if len(newMorph.Name) > 64 {
resp := &oapi.BadRequest{"Invalid value"}
return ctx.JSON(http.StatusBadRequest, resp)
}
morph := writeData("data.json", newMorph)
return ctx.JSON(http.StatusOK, &morph)
}
func (c controller) GetMorphById(ctx echo.Context, id oapi.Id) error {
morphs := readData("data.json")
for _, m := range morphs {
if m.Id == id {
return ctx.JSON(http.StatusOK, &m)
}
}
resp := &oapi.NotFound{"Not found"}
return ctx.JSON(http.StatusNotFound, &resp)
}
// dataaccess
func readData(filepath string) oapi.Morphs {
data, _ := ioutil.ReadFile(filepath)
var morphs oapi.Morphs
json.Unmarshal(data, &morphs)
return morphs
}
func writeData(filepath string, newMorph *oapi.NewMorph) oapi.Morph {
morphs := readData(filepath)
id := len(morphs) + 1
morph := oapi.Morph{
Id: id,
Name: newMorph.Name,
}
morphs = append(morphs, morph)
f, err := os.OpenFile(filepath, os.O_WRONLY, 0666)
if err != nil {
panic(err)
}
defer f.Close()
if err = json.NewEncoder(f).Encode(morphs); err != nil {
panic(err)
}
return morph
}
func main() {
e := echo.New()
c := controller{}
oapi.RegisterHandlers(e, c)
e.Logger.Fatal(e.Start(":8888"))
}
data.json
[]
stepciインストールとファイル生成
Homebrewでインストールします。
$ brew install stepci
ワークフローファイル生成コマンドのstepci generateのヘルプを確認します。
対象のopenapi定義ファイルと生成先ファイルを引数で順に渡せばいいようです。
$ stepci generate --help
ⓘ Anonymous usage data collected. Learn more on https://step.ci/privacy
stepci generate [spec] [path]
generate workflow from OpenAPI spec
位置:
spec openapi file url [文字列] [デフォルト: "openapi.json"]
path output file path
...
生成コマンドをgen/gen.goに追記し、実行して生成します。(2行目が追記箇所)
gen/gen.go
//go:generate oapi-codegen -package oapi -include-tags "morphs" -o ../oapi/morphs.gen.go ../openapi.yml
//go:generate stepci generate ../openapi.yml ../workflow.yml
package main
func main() {}
$ go generate ./gen
ⓘ Anonymous usage data collected. Learn more on https://step.ci/privacy
Success! The workflow file can be found at ./workflow.yml
Give us your feedback on https://step.ci/feedback
workflow.ymlが以下の通り生成されました。
各リクエストでopenapiで定義したステータスとレスポンスボディが得られるかテストしてくれそうです。
stepsのgetMorphByIdのパスパラメータについては、openapi定義の該当パラメータのexample値が利用されます。未指定の場合はランダム生成の値になるため注意が必要そうです。
workflow.yml
version: "1.0"
name: step-ci-testing
config:
http:
baseURL: http://localhost:8888
tests:
morphs:
steps:
- id: getMorphs
http:
url: /morphs
method: GET
check:
status: 200
schema:
$ref: "#/components/schemas/Morphs"
- id: postMorph
http:
url: /morphs
method: POST
headers:
Content-Type: application/json
accept: application/json
json:
name: sed magna in
check:
status: 200
schema:
$ref: "#/components/schemas/Morph"
- id: getMorphById
http:
url: /morphs/1
method: GET
check:
status: 200
schema:
$ref: "#/components/schemas/Morph"
components:
schemas:
Morph:
allOf:
- type: object
required:
- id
properties:
id:
type: integer
example: 1
- $ref: "#/components/schemas/NewMorph"
NewMorph:
type: object
required:
- name
properties:
name:
type: string
example: Normal
Morphs:
type: array
items:
$ref: "#/components/schemas/Morph"
Id:
type: integer
example: 1
テスト
サーバを起動します。
$ go run ./main.go
____ __
/ __/___/ / ___
/ _// __/ _ \/ _ \
/___/\__/_//_/\___/ v4.9.0
High performance, minimalist Go web framework
https://echo.labstack.com
____________________________________O/_______
O\
⇨ http server started on [::]:8888
stepciテストを実行します。
無事テストが通りました！
$ stepci run ./workflow.yml
ⓘ Anonymous usage data collected. Learn more on https://step.ci/privacy
PASS morphs
Tests: 0 failed, 1 passed, 1 total
Steps: 0 failed, 0 skipped, 3 passed, 3 total
Time: 0.112s, estimated 0s
CO2: 0.00007g
Workflow passed after 0.112s
Give us your feedback on https://step.ci/feedback
所感
最低限のテストとして簡単に生成できるのはとても良いなと思う反面、異常系については結局自分でworkflowを書く必要があるので、規模が大きくなるにつれ自動生成は使わなくなるかもと思いました。
複数のworkflowをincludeして実行といったこともできるようなので、自動生成した正常系と手動作成の異常系の2ファイルで運用もありですかね。
-> workflow.ymlをincludeするworkflow_main.ymlを作成してみたが、エラーで実行できず。詳細はちょっと調べましたがわかっておらずです。
workflow_main.yml
version: "1.0"
name: step-ci-testing
include:
- workflow.yml
エラー
$ stepci run ./workflow_main.yml
ⓘ Anonymous usage data collected. Learn more on https://step.ci/privacy
FAIL morphs
Summary
✕ getMorphs failed after 0.065s
⚠︎ postMorph skipped after 0s
⚠︎ getMorphById skipped after 0s
⚠︎ morphs › undefined
can't resolve reference #/components/schemas/Morphs from id #
⚠︎ morphs › undefined
Step was skipped because previous one failed
⚠︎ morphs › undefined
Step was skipped because previous one failed
Tests: 1 failed, 0 passed, 1 total
Steps: 3 failed, 2 skipped, 0 passed, 3 total
Time: 0.095s, estimated 0s
CO2: 0.00007g
Workflow failed after 0.095s
Give us your feedback on https://step.ci/feedback
Discussion