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