API 定义完整示例

api 示例

下文仅展示 api 文件的完整写法和对应语法块的功能说明，如需查看 api 规范定义，可参考 《API 规范》

  1. syntax = "v1"
  3. info (
  4.     title:   "api 文件完整示例写法"
  5.     desc:    "演示如何编写 api 文件"
  6.     author:  "keson.an"
  7.     date:    "2022 年 12 月 26 日"
  8.     version: "v1"
  9. )
  11. type UpdateReq {
  12.     Arg1 string `json:"arg1"`
  13. }
  15. type ListItem {
  16.     Value1 string `json:"value1"`
  17. }
  19. type LoginReq {
  20.     Username string `json:"username"`
  21.     Password string `json:"password"`
  22. }
  24. type LoginResp {
  25.     Name string `json:"name"`
  26. }
  28. type FormExampleReq {
  29.     Name string `form:"name"`
  30. }
  32. type PathExampleReq {
  33.     // path 标签修饰的 id 必须与请求路由中的片段对应，如
  34.     // id 在 service 语法块的请求路径上一定会有 :id 对应，见下文。
  35.     ID string `path:"id"`
  36. }
  38. type PathExampleResp {
  39.     Name string `json:"name"`
  40. }
  42. @server (
  43.     jwt:        Auth // 对当前 Foo 语法块下的所有路由，开启 jwt 认证，不需要则请删除此行
  44.     prefix:     /v1 // 对当前 Foo 语法块下的所有路由，新增 /v1 路由前缀，不需要则请删除此行
  45.     group:      g1 // 对当前 Foo 语法块下的所有路由，路由归并到 g1 目录下，不需要则请删除此行
  46.     timeout:    3s // 对当前 Foo 语法块下的所有路由进行超时配置，不需要则请删除此行
  47.     middleware: AuthInterceptor // 对当前 Foo 语法块下的所有路由添加中间件，不需要则请删除此行
  48.     maxBytes:   1024 // 对当前 Foo 语法块下的所有路由添加请求体大小控制，单位为 byte,goctl 版本 >= 1.5.0 才支持
  49. )
  50. service Foo {
  51.     // 定义没有请求体和响应体的接口，如 ping
  52.     @handler ping
  53.     get /ping
  55.     // 定义只有请求体的接口，如更新信息
  56.     @handler update
  57.     post /update (UpdateReq)
  59.     // 定义只有响应体的结构，如获取全部信息列表
  60.     @handler list
  61.     get /list returns ([]ListItem)
  63.     // 定义有结构体和响应体的接口，如登录
  64.     @handler login
  65.     post /login (LoginReq) returns (LoginResp)
  67.     // 定义表单请求
  68.     @handler formExample
  69.     post /form/example (FormExampleReq)
  71.     // 定义 path 参数
  72.     @handler pathExample
  73.     get /path/example/:id (PathExampleReq) returns (PathExampleResp)
  74. }