Goa v1 と v3 の DSL の比較

前回の記事ではプリミティブ型の比較を行いましたが、今回は DSL の比較を行っていきます。各 DSL の詳細については随時追記していきます。

v1 v3
API API
APIKeySecurity APIKeySecurity
(APIKey)
(APIKeyField)
AccessCodeFlow (廃止) -
Action Method
ApplicationFlow (廃止) -
ArrayOf ArrayOf
Attribute Attribute
Attributes Attributes
BasePath Path
BasicAuthSecurity BasicAuthSecurity
(Password)
(PasswordField)
(Username)
(UsernameField)
CONNECT CONNECT
CanonicalActionName CanonicalMethod
CollectionOf CollectionOf
Consumes Consumes
Contact Contact
ContentType ContentType
Credentials (goa.design/plugins/cors に移動) -
DELETE DELETE
Default Default
DefaultMedia (廃止) -
Description Description
Docs Docs
Email Email
Enum Enum
Example Example
(Value)
Expose (goa.design/plugins/cors に移動) -
Files Files
Format Format
Function (廃止) -
GET GET
HEAD HEAD
HashOf MapOf
Header Header
Headers Headers
Host Host
Server
URI
Variable
ImplicitFlow ImplicitFlow
JWTSecurity JWTSecurity
(Token)
(TokenField)
License License
Link (廃止) -
Links (廃止) -
MaxAge (goa.design/plugins/cors に移動) -
MaxLength MaxLength
Maximum Maximum
Media Result
MediaType ResultType
Member (廃止) -
Metadata Meta
Methods (goa.design/plugins/cors に移動) -
MinLength MinLength
Minimum Minimum
MultipartForm MultipartRequest
Name Name
NoExample (廃止) -
NoSecurity NoSecurity
OAuth2Security OAuth2Security
(AccessToken)
(AccessTokenField)
OPTIONS OPTIONS
OptionalPayload (廃止) -
Origin (goa.design/plugins/cors に移動) -
PATCH PATCH
POST POST
PUT PUT
Package (廃止) -
Param Param
Params Params
Parent Parent
PasswordFlow PasswordFlow
Pattern Pattern
Payload Payload
Produces Produces
Query (廃止) -
ReadOnly (廃止) -
Reference Reference
Required Required
Resource Service
Response Response
ResponseTemplate (廃止) -
Routing (廃止) -
Scheme (廃止) -
Scope Scope
Security Security
Status Code
TRACE TRACE
TermsOfService TermsOfService
Title Title
TokenURL (廃止) -
Trait (廃止) -
Type Type
TypeName TypeName
URL URL
UseTrait (廃止) -
Version Version
View View
- AuthorizationCodeFlow
- Body
- ClientCredentialsFlow
- ConvertTo
- CreateFrom
- Elem
- Error
- Extend
- Fault
- Field
- GRPC
- HTTP
- Key
- MapParams
- Message
- Metadata
- Services
- StreamingPayload
- StreamingResult
- Tag
- Temporary
- Timeout
- Trailers

BasePath

  • Path に変更されました。
  • HTTP 内に記述します。
// v1
BasePath("/users")

// v3
HTTP(func() {
    Path("/users")
})

Consumes, Produces

  • HTTP 内に記述します。
  • これらの DSL 内で使用できた Function と Package は廃止されました。
// v1
Consumes("application/xml")
Consumes("application/json")
Produces("application/xml")
Produces("application/json")

// v3
HTTP(func() {
    Consumes("application/xml")
    Consumes("application/json")
    Produces("application/xml")
    Produces("application/json")
})

Format

  • v1 では引数の型が string でしたが、 v3 では expr.ValidationFormat になりました。
  • 使用可能な expr.ValidationFormat は goa.design/goa/expr に const として定義されています。

GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH

  • v1 ではパスパラメータをコロン (:) で記述しましたが、 v3 では中括弧 ({, }) を使います。
// v1
GET("/users/:id")

// v3
GET("/users/{id}")

HashOf

  • MapOf に変更されました。
  • key のためのオプション DSL は Key で記述します。
  • value のためのオプション DSL は Elem で記述します。
// v1
HashOf(String, Integer,
    func() {
        MinLength(1)
        MaxLength(16)
    },
    func() {
        Minimum(1)
        Maximum(5)
    },
)

// v3
MapOf(String, Int, func() {
    Key(func() {
        MinLength(1)
        MaxLength(16)
    })
    Elem(func () {
        Minimum(1)
        Maximum(5)
    })
})

Headers

リクエストヘッダ

  • Payload 内に Attribute を、 HTTP 内に Headers を記述します。
// v1
Action("show", func() {
    Headers(func() {
        Header("Authorization", String)
    })
})

// v3
Method("show", func() {
    Payload(func() {
        Attribute("Authorization", String)
    })
    HTTP(func() {
        Headers(func() {
            Header("Authorization", String)
        })
    })
})

Host, Scheme

  • v1 では Host と Scheme (と BasePath) で記述しましたが、 v3 では Server と Host と URI を使います。
// v1
Host("localhost:8080")
Scheme("http")
BasePath("/cellar")

// v3
Server("app", func() {
    Host("development", func() {
        URI("http://localhost:8080/cellar")
    })
})

NoExample

  • 廃止されました。
  • Meta で同等の定義ができます。
Meta("swagger:example", "false")

Params

パスパラメータ

  • Payload 内に Attribute を、 HTTP 内に Params を記述します。
  • Params は省略できます。省略した場合は暗黙的に定義されます。
// v1
Action("show", func() {
    Params(func() {
        Param("id", Integer)
    })
})

// v3
Method("show", func() {
    Payload(func() {
        Attribute("id", Int)
    })
    HTTP(func() {
        Params(func() {       // 省略可
            Param("id", Int)  //
        })                    //
    })
})

クエリパラメータ

  • Payload 内に Attribute を、 HTTP 内に Params を記述します。
  • Params は省略できません。
//v1
Action("list", func() {
    Params(func() {
        Param("name", String)
    })
})

// v3
Method("list", func() {
    Payload(func() {
        Attribute("name", String)
    })
    HTTP(func() {
        Params(func() {            // 省略不可
            Param("name", String)  //
        })                         //
    })
})

Routing

  • 廃止されました。
  • HTTP 内に HTTP リクエストメソッドと同名の DSL を記述します。
// v1
Action("show", func() {
    Routing(
        GET("/:id"),
    )
})

// v3
Method("show", func() {
    HTTP(func() {
        GET("/{id}")
    })
})