goa API デザイン言語

import (
    . "github.com/goadesign/goa/design"
    . "github.com/goadesign/goa/design/apidsl"
)

var _ = API("My API", func() {        // "My API" is the name of the API used in docs
    Title("Documentation title")      // Documentation title
    Description("The next big thing") // Longer documentation description
    Host("goa.design")                // Host used by Swagger and clients
    Scheme("https")                   // HTTP scheme used by Swagger and clients
    BasePath("/api")                  // Base path to all API endpoints
    Consumes("application/json")      // Media types supported by the API
    Produces("application/json")      // Media types generated by the API
})

var _ = Resource("Operands", func() {        // Defines the Operands resource
    Action("add", func() {                   // Defines the add action
        Routing(GET("/add/:left/:right"))    // The relative path to the add endpoint
        Description("add returns the sum of :left and :right in the response body")
        Params(func() {                      // Defines the request parameters
                                             // found in the URI (wildcards) and querystring
            Param("left", Integer, "Left operand")   // Defines left parameter as path segment
                                                     // captured by :left
            Param("right", Integer, "Right operand") // Define right parameter as path segment
                                                     // captured by :right
        })
        Response(OK, "plain/text")           // Defines response
    })
})

Param("left", Integer, "Left operand", func() {
    Minimum(0) // Do not allow for negative values.
})

var _ = Resource("public", func() {

    Origin("*", func() {        // CORS policy that applies to all actions and file servers
        Methods("GET")          // of "public" resource
    })

    Files("/swagger.json", "public/swagger/swagger.json", func() {
        Security("basic_auth")  // Security scheme implemented by /swagger.json endpoint
    })

    Files("/js/*filepath", "public/js/") // Serve all files under the public/js directory
})

// Operand describes a single operand with a name and an integer value.
var Operand = Type("Operand", func() {
    Attribute("name", String, "Operand name", func() { // Attribute name of type string
        Pattern("^x")                                  // with regex validation
    })
    Attribute("value", Integer, "Operand value")  // Attribute value of type integer
    Required("value")                             // only value is required
})

// Series represents an array of operands.
var Series = ArrayOf(Operand)

Action("sum", func() {          // Defines the sum action
    Routing(POST("/sum"))       // The relative path to the add endpoint
    Description("sum returns the sum of all the operands in the response body")
    Payload(Series)             // Defines the action request body shape using the Series
                                // type defined above.
    Response(OK, "plain/text")  // Defines a response
})

Attribute(<name>, <type>, <description>, <dsl>)

var User = Type("user", func() {
    Description("A user of the API")
    Attribute("name")                 // Simple string attribute
    Attribute("address", func() {     // Nested definition, defines a struct in Go
        Attribute("number", Integer, "Street number")
        Attribute("street", String, "Street name")
        Attribute("city", String, "City")
        Required("city")              // The address must contain at least a city
    })
    Attribute("friends", ArrayOf("user"))
    Attribute("data", HashOf(String, String))
})

// Results is the media type that defines the shape of the "add" action response.
var Results = MediaType("vnd.application/goa.results", func() {
    Description("The results of an operation")
    Attributes(func() {                              // Defines the media type attributes
        Attribute("value", Integer, "Results value") // Operation results attribute
        Attribute("requester", User)                 // Requester attribute
    })
    Links(func() {             // Defines the links embedded in the media type
        Link("requester")      // One link to the requester, will be rendered
                               // using the "link" view of User media type.
    })
    View("default", func() {   // Defines the default view
        Attribute("value")     // Includes the "value" field in the default view
        Links()                // And render links
    })
    View("extended", func() {  // Defines the extended view
        Attribute("value")     // Includes the value field
        Attribute("requester") // and the requester field
    })
})

// User is the media type used to render user resources.
var User = MediaType("vnd.application/goa.users", func() {
    Description("A user of the API")
    Attributes(func() {
        Attribute("id", UUID, "Unique identifier")
        Attribute("href", String, "User API href")
        Attribute("email", String, "User email", func() {
            Format("email")
        })
    })
    View("default", func() {
        Attribute("id")
        Attribute("href")
        Attribute("email")
    })
    View("link", func() { // The view used to render links to User media types.
        Attribute("href") // Here only the href attribute is rendered in links.
    })
})

Response("NoContent", func() {
    Description("This is the response returned in case of success")
    Status(204)
})

Response(NoContent)

Response("OK", func() {
    Description("This is the success response")
    Status(200)
    Media(Results)
})

Response("OK", Results, func() {
    Description("This is the success response")
    Status(200)
})

Response("OK", "application/vnd.example.results", func() {
    Description("This is the success response")
    Status(200)
})

Response("OK", func() {
    Description("This is the success response")
    Status(200)
    Media(Results, "default")
})

Response("OK", func() {
    Status(200)
    Media(Results, "default")
    Headers(func() {
        Header("Location", String, "Resource location", func() {
            Pattern("/results/[0-9]+")
        })
        Header("ETag") // assumes String type as with Attribute
    })
})

var _ = Resource("Operands", func() {
    Response("Unauthorized", func() {
        Description("Response sent for unauthorized requests")
        Status(401)
    })
    Action("add", func() {
        Routing(GET("/add/:left/:right"))
        Params(func() {
            Param("left", Integer, "Left operand")
            Param("right", Integer, "Right operand")
        })
        Response("OK", Results)
        // Response "Unauthorized" is implicit
    })
})

var _ = Resource("Operands", func() {
    DefaultMedia(Results)
    Action("add", func() {
        Routing(GET("/add/:left/:right"))
        Params(func() {
            Param("left", Integer, "Left operand")
            Param("right", Integer, "Right operand")
        })
        Response(OK)         // Uses the resource default media type
    })
})

var Results = MediaType("vnd.application/goa.results", func() {
    Description("The results of an operation")
    Attributes(func() {
        Attribute("left", Integer, "Left operand")
        Attribute("right", Integer, "Right operand")
        Attribute("value", Integer, "Results value")
        Attribute("requester", User)
    })
    View("default", func() {
        Attribute("left")
        Attribute("right")
        Attribute("value")
        Attribute("requester")
    })
})

var _ = Resource("Operands", func() {
    DefaultMedia(Results)
    Action("add", func() {
        Routing(GET("/add/:left/:right"))
        Params(func() {
            Param("left")    // Inherits type and description from default media type
            Param("right")   // Inherits type and description from default media type
        })
        Response(OK)         // Uses the resource default media type
    })
})

var _ = API("My API", func() {
    ResponseTemplate("created", func(hrefPattern string) { // Defines the "created" template
        Description("Resource created")                    // that takes one argument "hrefPattern"
        Status(201)                     // using status code 201
        Header("Location", func() {     // and contains the "Location" header
            Pattern(hrefPattern)        // with a regex validation defined by the
                                        // value of the "hrefPattern" argument.
        })
    })
})

Action("sum", func() {
    Routing(POST("/accounts"))
    Payload(AccountPayload)
    Response("created", "^/results/[0-9]+") // Response uses the "created" response template.
})

Action("show", func() {
    Routing(GET("/:id"))
    Response("ok", func() {
        Status(200)
        Media(AccountMedia)
    })
})

Action("show", func() {
    Routing(GET("/:id"))
    Response(OK, AccountMedia) // Uses the built-in "OK" response template that defines status 200
})