Download - goa Design first API Generation
CyberAgent, Inc. All Rights Reserved.
goa :: Design-first API Generation
2015 December 4th
Date : 2017 March 10 Presenter : Y.Sugiyama
Who are you?01
Introduction Who are you?01
CyberAgent(2011~)• Ameba Pigg
• Java, node.js, MongoDB• Takusuta(Live Streaming)
• Golang(gin), node.js, python, MongoDB,and various on live streaming.• Golang, node.js, a little Scala.
Yoshinori Sugiyama,age:36,github:syama666
What is goa?02
goa has three parts What is goa?02
• a Go DSL for describing the microservice API• a tool for generating code and documentation from design DSL• a library to support the implementation of microservices
design03
DSL examples for API design design03
// GET /v1/kings?page=1&perPage=10&sort=-kingsIdvar _ = Resource("v1_kings", func() {
BasePath("/v1/kings")Action("list", func() {
Routing(GET(""))Description(”get kings list")Param("page", Integer, "e.g.) page=1", func() {
Default(1)})Param("perPage", Integer, "e.g.) perPage=10", func() {
Default(10)})Param("sort", String, "e.g.) sort=kingId or sort=-
kingId", func() {Pattern("^-?[0-9a-zA-Z]+$")Default("-kingId")
})Response(OK, func() {
Media(ResponseKings)})
})})
DSL examples for API design design03
// PUT/v1/kings/1192var _ = Resource("v1_kings", func() {
BasePath("/v1/kings")Action("update", func () {
Routing(PUT("/:kingId"))Description(”update
a king")Params(func() {
Param("kingId", Integer)})Payload(UpdateKing)Response(OK, func()
{
Media(ResponseOneKing)})
})})
DSL examples for API design design03
// base king type dslvar baseKing = Type("baseKing", func() { Attribute("kingId", Integer, func() { Example(1192) }) Attribute("name", String, func() { Example("Louis XIV") }) Attribute("age", Integer, func() { Example(76) })})
DSL examples for API design design03
// Japanese Lord type dslvar japaneseLord = Type("baseKing", func() { Reference(baseKing) Attribute("kingId") Attribute("name") Attribute("age") Attribute("birthPlace", String, func(){ Example(“ ”江戸 ) }) Required( "kingId", "name", "age", "birthPlace", )})
DSL to Swagger design03
Goa DSL to Swagger.json By goagen
API design lifecycle design03
Generating code and docs04
goagen’s sub commands Generating04
• main• main.go and controller scaffolding
• controller• only controller scaffolding
• app• validation, context, etc
• client• golang client
• swagger• swagger json
• js• javascript client
• schema• JSON schema
directory/package structure Generating04
• main.go• controller/• gen/
• app/• contexts.go• controllers.go• hrefs.go• user_types.go• media_types.go
• swagger/• swagger.json• swagger.yml
• design/
directory/package structure Generating04
• main.go• controller/• gen/
• app/• contexts.go• controllers.go• hrefs.go• user_types.go• media_types.go
• swagger/• swagger.json• swagger.yml
• design/
main
app
swagger
directory/package structure Generating04
• main.go• controller/• gen/
• app/• contexts.go• controllers.go• hrefs.go• user_types.go• media_types.go
• swagger/• swagger.json• swagger.yml
• design/
auto-generated, do not modify
Only scaffold, goa do not update
05 Overall view
lib,generated, and yours Overall view05
Components structure Overall view05
API sequence Overall view05
06 digest
cool digest06
• Generating swagger docs.• Generating validation-code, and scaffolding some.
• Output a better code than go-swagger -> https://github.com/go-swagger/go-swagger
not cool digest06
• You need implements logic of convert from your model sturct to goa-generated struct.
• If you want to customize the error response, you have to hack goa - middleware.
https://github.com/goadesign/goa/issues/1076