社内勉強会用資料

1. CyberAgent, Inc. All Rights Reserved.
goa :: Design-first API Generation
2015 December 4th
Date : 2017 March 10 Presenter : Y.Sugiyama

2. Who are you?01

3. 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

4. What is goa?02

5. 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

6. design03

7. DSL examples for API design design03
// GET /v1/kings?page=1&perPage=10&sort=-kingsId
var _ = 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)
})

8. DSL examples for API design design03
// PUT/v1/kings/1192
var _ = 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)
})
})

9. DSL examples for API design design03
// base king type dsl
var baseKing = Type("baseKing", func() {
Attribute("kingId", Integer, func() {
Example(1192)
})
Attribute("name", String, func() {
Example("Louis XIV")
})
Attribute("age", Integer, func() {
Example(76)
})
})

10. DSL examples for API design design03
// Japanese Lord type dsl
var japaneseLord = Type("baseKing", func() {
Reference(baseKing)
Attribute("kingId")
Attribute("name")
Attribute("age")
Attribute("birthPlace", String, func(){
Example(“江戸”)
})
Required(
"kingId",
"name",
"age",
"birthPlace",
)
})

11. DSL to Swagger design03
Goa DSL to Swagger.json By goagen

12. API design lifecycle design03

13. Generating code and docs04

14. 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

15. 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/

16. 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

17. 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

18. 05 Overall view

19. lib,generated, and yours Overall view
05

20. Components structure Overall view
05

21. API sequence Overall view
05

22. 06 digest

23. 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

24. 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