goa tips: 小ネタ (swaggerドキュメントの抑制とパラメータ必須要素について)

概要

goa のちょっとしたネタです.

swagger ドキュメントに出したくない要素を抑制する

swagger ドキュメントに出したくない要素を Metadata() を利用して抑制することができるようになりました. 特定の Resource を出力したくなければ Resource() の下で Metadata("swagger:generate", "false") を設定します. ただし,配下の要素で Metadata("swagger:generate", "true") を指定すると,出力の指定を上書きして,そちらが優先になります.

https://github.com/goadesign/goa/pull/863

Resource("invisible", func() {
    Metadata("swagger:generate", "false")
    Action("visible", func() {
        Metadata("swagger:generate", "true") // Override resource swagger:generate metadata
   })
})

これで何がうれしいかというと,swagger-ui を立ち上げるときにうれしいです. swagger-ui を利用するときに Files() を利用してサービスを立ち上げることができるんですが, この swagger-ui をサービスしている API 自体が swagger ドキュメントに記載されてしまってもんにょりする問題がありました.

swagger-ui を立ち上げる方法については過去の記事を参照ください.

var _ = Resource("swagger", func() {
        Metadata("swagger:generate", "false")
        Files("/swagger.json", "swagger/swagger.json")
        Files("/swaggerui/*filepath", "swaggerui/dist")
})

こうしておくと,もんにょりする事態が回避できそうです.

# この機能使って panic が起こるようなら,最新の goa に update してみてください.

パラメータや Payload などの必須要素を忘れないようにする

Attribute を設定して,その後に Required() で必須要素を選択しますが,パラメータをいじったり,必須要素を変更してたりすると齟齬が出やすくなります. そこで,Attribute と Required を同時に設定するハックです.

func RequiredAttribute(name string, args ...interface{}) {
        Attribute(name, args...)
        Required(name)
}

こういう便利関数を用意しておくと,どれが必須要素かわかりやすいですし,オプションにするときも変更しやすいです.

var MyPayload = Type("My Payload", func() {
        RequiredAttribute("id", Integer, "required item") // 必須
        Attribute("name", String, "optional item")
})

こんなかんじ.