github.com/shogo82148/goa-v1@v1.6.2/design/apidsl/doc.go (about)

     1  /*
     2  Package apidsl implements the goa design language.
     3  
     4  The goa design language provides a simple way to describe an API design. The language consists of
     5  global Go functions that can be nested to build up *definitions*. The root definition is the API
     6  definition. This definition is what the language builds as it executes. There are 3 other top level
     7  definitions: the resource, media type and type definitions all created using the corresponding
     8  global functions (Resource, MediaType and Type).
     9  
    10  Resource definitions describe the API resources. This includes the default media type used to
    11  represent the resource as well as all the actions that can be run on it.
    12  
    13  Media type definitions describe the media types used throughout the API. A media type describes
    14  the body of HTTP responses by listing their attributes (think object fields) in a recursive manner.
    15  This description can also include JSON schema-like validation rules that goa uses to produce
    16  validation code. A Media type definition also describes one or more *views* and for each view which
    17  fields to render. Finally a media type definition may also define *links* to other resources. The
    18  media type used to render the link on a resource defines a special "link" view used by default by
    19  goa to render the "links" child attributes.
    20  
    21  The last top level definition is the type definition. Type definitions describe data structures
    22  in a similar way that media type definitions describe response body attributes. In fact, media
    23  type definitions are a special kind of type definitions that add views and links. Type definitions
    24  can be used to describe the request payloads as a whole or any attribute appearing anywhere
    25  (payloads, media types, headers, params etc.) and as with media type definitions they can include
    26  validation rules that goa leverages to validate attributes of that type.
    27  
    28  Package apidsl also provides a generic DSL engine that other DSLs can plug into. Adding a DSL
    29  implementation consists of registering the root DSL object in the design package Roots variable.
    30  The runner iterates through all root DSL definitions and executes the definition sets they expose.
    31  
    32  In general there should be one root definition per DSL (the built-in API DSL uses the APIDefinition
    33  as root definition). The root definition can in turn list sets of definitions where a set defines
    34  a unit of execution and allows to control the ordering of execution. Each definition set consists
    35  of a list of definitions. Definitions must implement the design.Definition interface and may
    36  additionally implement the design.Source and design.Validate interfaces.
    37  */
    38  package apidsl