Key: @kok(op)

Value: <method> <pattern>

• method: The request method
• pattern: The request URL
  • NOTE: All variables in pattern will automatically be bound to their corresponding method arguments (matches by name in lower camel case), as path parameters, if the variables are not yet 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.
  • Blank identifier: By specifying the argName with a double underscore prefix __, the corresponding request parameter(s) will not be mapped to any method argument. See here for more details.
• in:
  • path: The method argument is sourced from a path parameter.
    • Optional: All variables in pattern will automatically be bound to their corresponding method arguments (matches by name in lower camel case), 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 (snake-case, or lower-camel-case if -snake=false) 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 (snake-case, or lower-camel-case if -snake=false) 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)
}

Key: @kok(oas)

Value: <property>:<value>

• <property>: The property to set. Supported properties:
  • docsPath: The URL path to the OAS documentation itself.
    • Optional: Defaults to "/api" if not specified.
  • title: The title field of Info Object, see Basic Structure.
    • Optional: Defaults to "No Title" if not specified.
  • version: The version field of Info Object, see Basic Structure.
    • Optional: Defaults to "0.0.0" if not specified.
  • description: The description field of Info Object, see Basic Structure.
    • Unavailable: Automatically extracted from the Go documentation of the interface definition.
  • basePath: The basePath property, see API Host and Base URL.
  • tags: A list of tags (comma-separated), see Grouping Operations With Tags.
• <value>: The value of the property.

Example:

// This is the API documentation of User.
// @kok(oas): docsPath:/api-docs
// @kok(oas): title:User API
// @kok(oas): version:1.0.0
// @kok(oas): basePath:/v1
// @kok(oas): tags:user
type Service interface {
    // @kok(op): POST /users
    CreateUser(ctx context.Context, name string, age int) (err error)
}

Key: @kok(alias)

Value: <name>=`<value>`

• <name>: The name of the alias.
• <value>: The string value that the alias represents.

Example:

type Service interface {
    // @kok(op): POST /users
    // @kok(param): operatorID < in:header,name:Authorization,required:true
    CreateUser(ctx context.Context, operatorID int) (err error)

    // @kok(op): DELETE /users/{id}
    // @kok(param): operatorID < in:header,name:Authorization,required:true
    DeleteUser(ctx context.Context, id, operatorID int) (err error)
}

// The equivalent annotations =>

// @kok(alias): opID=`operatorID < in:header,name:Authorization,required:true`
type Service interface {
    // @kok(op): POST /users
    // @kok(param): $opID
    CreateUser(ctx context.Context, operatorID int) (err error)

    // @kok(op): DELETE /users/{id}
    // @kok(param): $opID
    DeleteUser(ctx context.Context, id, operatorID int) (err error)
}