goswagger触ったときのメモ

やること

• 導入
  • swagger-codegen install?
  • goswagger install
• サンプルプロジェクトの作成
  • pj準備
  • project generate
  • 自動生成されたもの確認
  • 起動
  • 初回API実行
• API実装
  • API実装
  • API実行 ​

環境

• macOS Catalina(Version 10.15.7) ​

swagger-codegen install?

brew update
brew install swagger-codegen

pj準備

mkdir samplepj/goswagger-sample
go mod init samplepj.com/goswagger-sample

goswagger install

go get -u github.com/go-swagger/go-swagger/cmd/swagger

goswagger準備

• yaml作成
  • GOPATH配下に置く(置かなくても良かった
    • $GOPATH/src/swagger
  • ここちらを参考にしました(https://qiita.com/o_tyazuke/items/43bd362e8e427aa0e340)

swagger: "2.0"
info:
  version: "0.0.1"
  title: "samplepj"
  description: "sample project"
host: "localhost:8000"
basePath: "/api"
schemes:
  - "http"
consumes:
  - "application/json"
produces:
  - "application/json"
paths:
  /user:
    post:
      operationId: postUser
      parameters:
      - in: body
        name: body
        required: true
        schema:
          $ref: '#/definitions/User'
      responses:
        '201':
          description: Created
  /user/{id}:
    get:
      operationId: getUserById
      parameters:
      - name: "id"
        in: "path"
        required: true
        type: "string"
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/User'
definitions:
  User:
    type: object
    properties:
      id:
        type: number
        format: uint
      name:
        type: string

project generate

オプション等 https://goswagger.io/generate/server.html ​

swagger generate server -f swagger.yaml

自動生成されたもの確認

.
├── cmd
│   └── samplepj-server
│       └── main.go
├── go.mod
├── go.sum
├── models
│   └── user.go
└── restapi
    ├── configure_samplepj.go
    ├── doc.go
    ├── embedded_spec.go
    ├── operations
    │   ├── get_user_by_id.go
    │   ├── get_user_by_id_parameters.go
    │   ├── get_user_by_id_responses.go
    │   ├── get_user_by_id_urlbuilder.go
    │   ├── post_user.go
    │   ├── post_user_parameters.go
    │   ├── post_user_responses.go
    │   ├── post_user_urlbuilder.go
    │   └── samplepj_api.go
    └── server.go

起動

$ go mod tidy
go: downloading gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f
go: downloading github.com/google/go-cmp v0.5.5
​
$ go run cmd/samplepj-server/main.go --port=8080
2021/06/02 12:53:12 Serving samplepj at http://127.0.0.1:8080

初回API実行

実装してないので下記メッセージが発生する

$ curl http://127.0.0.1:8080/api/user/1
"operation GetUserByID has not yet been implemented"

API実装

• restapi配下にhandler dirを作成

mkdir handler
​
.
└── restapi
    └── handler
        └── get_user_by_id.go
​

• handler

package handler
​
import (
    "strconv"
​
    "github.com/go-openapi/runtime/middleware"
​
    "sample.com/swagger/models"
    "sample.com/swagger/restapi/operations"
)
​
type GetUserByIDHandler struct {}
​
func (h *GetUserByIDHandler) Handle(params operations.GetUserByIDParams) middleware.Responder {
    id, _ := strconv.ParseUint(params.ID, 10, 64)
​
    u := models.User{id, "test"}
​
    return operations.NewGetUserByIDOK().WithPayload(&u)
}

• restapi/configure_samplepj.goの変更
  • line: 41あたり

​
if api.GetUserByIDHandler == nil {
  // api.GetUserByIDHandler = operations.GetUserByIDHandlerFunc(func(params operations.GetUserByIDParams) middleware.Responder {
  //   return middleware.NotImplemented("operation operations.GetUserByID has not yet been implemented")
  // })
  api.GetUserByIDHandler = operations.GetUserByIDHandlerFunc(func(params operations.GetUserByIDParams) middleware.Responder {
    h := handler.GetUserByIDHandler{}
    return h.Handle(params)
  })
}

• operations/samplepj_api.go編集
  • line: 45あたりをコメントアウト
  • restapi/configure_samplepj.go で同じhandler使うので起動時にエラーが発生する
    • import cycle not allowed

//GetUserByIDHandler: GetUserByIDHandlerFunc(func(params GetUserByIDParams) middleware.Responder {
//  return middleware.NotImplemented("operation GetUserByID has not yet been implemented")
//}),

API実行

$ go run cmd/samplepj-server/main.go --port=8080
2021/06/02 13:26:33 Serving samplepj at http://127.0.0.1:8080
​
$ curl http://127.0.0.1:8080/api/user/1
{"id":1,"name":"test"}