// syntax: specify the api syntax version,
// through this version can be a good control
// api syntax upgrade incompatibility issues
syntax = "v1"

// Info block is a key-value pair description body,
// you can add some descriptions of the current api
// file through this description body, you can add
// any key-value pair, which does not participate in the api generation
info(
    title: sample of api
    desc: "you can add a newline
description by quotes"
    author: songmeizi
    anyAnotherKey: anyTnotherValue
)

// The structure in the api evolved from the structure of golang,
// and it is also reserved to support the structure of golang.

// a golang structure
type Foo struct{
    Foo int
}

// api structure
type Bar {
    Bar int
}

// structure group
type (
    FooBar {
        Foo int
        Bar bool
    }
)

// Like the info block, @server can define any key-value pair.
// The difference is that @server is a description of the service
// block or route, which will participate in the api file generation.
// There are several important keys that need to be understood,
// which have special meanings. The jwt key is to declare that code
// generation needs to include jwt authentication logic. The group key
// is to declare that the files generated by the code need to be grouped
// according to the value corresponding to the group. The handler key
// determines the handler in golang. Layer file logic generation
@server(
    jwt: Auth
    group: foo
    anyAnotherKey: anyTnotherValue
)

// service block is the description of the api service,
// including @doc block, @handler and api routing information
service foo-api {
    // shortening doc declaration
    @doc("foo")
    // shortening handler declaration
    @handler foo
    // route
    get /foo (Foo) returns (Bar)


    @doc(
        summary: foo
    )
    @server(
        handler: bar
    )
    post /bar (Foo)
}