Key: @kok(op)

Value: <method> <pattern>

• method: The request method
• pattern: The request URL
  • NOTE: All variables (snake-case or camel-case) in pattern will automatically be bound to their corresponding method arguments (matches by name), as path parameters, if the variables are not specified as path parameters explicitly by @kok(param).

Example:

type Service interface {
    // @kok(op): DELETE /users/{id}
    DeleteUser(ctx context.Context, id int) (err error)
}

// HTTP request:
// $ http DELETE /users/101

• argName: The name of the method argument.
  • Argument aggregation: By specifying the same argName, multiple request parameters (each one is of basic type or repeated basic type) can be aggregated into one method argument (of any type).
    • You do not need to repeat the argName, only the first one is required.
• in:
  • path: The method argument is sourced from a path parameter.
    • Optional: All variables (snake-case or camel-case) in pattern will automatically be bound to their corresponding method arguments (matches by name), as path parameters.
  • query: The method argument is sourced from a query parameter.
    • To receive values from a multi-valued query parameter, the method argument can be defined as a slice of basic type.
  • header: The method argument is sourced from a header parameter.
  • cookie: The method argument is sourced from a cookie parameter.
    • Not supported yet.
  • request: The method argument is sourced from a property of Go's http.Request.
    • This is a special case, and only one property RemoteAddr is available now.
    • Note that parameters located in request have no relationship with OAS.
• name: The name of the corresponding request parameter.
  • Optional: Defaults to argName if not specified.
• descr: The OAS description of the corresponding request parameter.
  • Optional: Defaults to "" if not specified.
• required: Determines whether this parameter is mandatory.
  • Optional: Defaults to false, if not specified.
  • If the parameter location is path, this property will be set to true internally, whether it's specified or not.

• Bind request parameters to simple arguments:

  type Service interface {
      // @kok(op): PUT /users/{id}
      // @kok(param): name < in:header,name:X-User-Name
      UpdateUser(ctx context.Context, id int, name string) (err error)
  }
  
  // HTTP request:
  // $ http PUT /users/101 X-User-Name:tracey

• Bind multiple request parameters to a struct according to tags:

  type User struct {
      ID   int    `kok:"path.id"`
      Name string `kok:"query.name"`
      Age  int    `kok:"header.X-User-Age"`
  }
  
  type Service interface {
      // @kok(op): PUT /users/{id}
      // @kok(param): user
      UpdateUser(ctx context.Context, user User) (err error)
  }
  
  // HTTP request:
  // $ http PUT /users/101?name=tracey X-User-Age:1

• Bind multiple query parameters to a struct with no tags:

  type User struct {
      Name    string
      Age     int
      Hobbies []string
  }
  
  type Service interface {
      // @kok(op): POST /users
      // @kok(param): user
      CreateUser(ctx context.Context, user User) (err error)
  }
  
  // HTTP request:
  // $ http POST /users?Name=tracey&Age=1&Hobbies=music&Hobbies=sport

• Argument aggregation:

  type Service interface {
      // @kok(op): POST /logs
      // @kok(param): ip < in:header,name:X-Forwarded-For
      // @kok(param): ip < in:request,name:RemoteAddr
      Log(ctx context.Context, ip net.IP) (err error)
  }
  
  // The equivalent annotations.
  type Service interface {
      // @kok(op): POST /logs
      // @kok(param): ip < in:header,name:X-Forwarded-For
      // @kok(param):    < in:request,name:RemoteAddr
      Log(ctx context.Context, ip net.IP) (err error)
  }
  
  // You must customize the decoding of `ip` later (conventionally in another file named `codec.go`).
  // See examples in the `Encoding and decoding` section.
  
  // HTTP request:
  // $ http POST /logs

• field: The name of the method argument whose value is mapped to the HTTP request body.
  • Optional: When omitted, a struct containing all the arguments, which are not located in path/query/header, will automatically be mapped to the HTTP request body.
  • The special name - can be used, to define that there is no HTTP request body. As a result, every argument, which is not located in path/query/header, will automatically be mapped to one or more query parameters.
• argName: The name of the method argument to be manipulated.
• name: The name of the corresponding request parameter.
  • Optional: Defaults to argName if not specified.
• descr: The OAS description of the corresponding request parameter.
  • Optional: Defaults to "" if not specified.

• Omitted:

  type Service interface {
      // @kok(op): POST /users
      CreateUser(ctx context.Context, name string, age int) (err error)
  }
  
  // HTTP request:
  // $ http POST /users name=tracey age=1

• Specified as a normal argument:

  type User struct {
      Name string `json:"name"`
      Age  int    `json:"age"`
  }
  
  type Service interface {
      // @kok(op): POST /users
      // @kok(body): user
      CreateUser(ctx context.Context, user User) (err error)
  }
  
  // HTTP request:
  // $ http POST /users name=tracey age=1

• Specified as -:

  type User struct {
      Name    string   `kok:"name"`
      Age     int      `kok:"age"`
      Hobbies []string `kok:"hobby"`
  }
  
  type Service interface {
      // @kok(op): POST /users
      // @kok(body): -
      CreateUser(ctx context.Context, user User) (err error)
  }
  
  // HTTP request:
  // $ http POST /users?name=tracey&age=1&hobby=music&hobby=sport

Key: @kok(success)

Value: statusCode:<statusCode>,body:<body>

• statusCode: The status code of the success HTTP response.
  • Optional: Defaults to 200 if not specified.
• body: The name of the response field whose value is mapped to the HTTP response body.
  • Optional: When omitted, a struct containing all the results (except error) will automatically be mapped to the HTTP response body.

Example:

type User struct {
    Name string `json:"name"`
    Age  int    `json:"age"`
}

type Service interface {
    // @kok(op): POST /users
    // @kok(success): statusCode:201,body:user
    CreateUser(ctx context.Context) (user User, err error)
}