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.
  • body: The method argument is sourced from the request body.
    • Deprecated: Use @kok(body) instead.
  • 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.
• type: The type of the corresponding request parameter.
  • Optional: Defaults to the type of the method argument, if not specified.
  • Required for Argument aggregation for generating correct OAS documentation.
• 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.

• Simple argument:

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

• Argument aggregation:

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

• 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.

• 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:"query.name"`
      Age     int      `kok:"query.age"`
      Hobbies []string `kok:"query.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)
}