update

api/example.api

@@ -0,0 +1,75 @@
+syntax = "v1"
+
+info (
+    title:   "api 文件完整示例写法"
+    desc:    "演示如何编写 api 文件"
+    author:  "keson.an"
+    date:    "2022 年 12 月 26 日"
+    version: "v1"
+)
+
+type UpdateReq {
+    Arg1 string `json:"arg1"`
+}
+
+type ListItem {
+    Value1 string `json:"value1"`
+}
+
+type LoginReq {
+    Username string `json:"username"`
+    Password string `json:"password"`
+}
+
+type LoginResp {
+    Name string `json:"name"`
+}
+
+type FormExampleReq {
+    Name string `form:"name"`
+}
+
+type PathExampleReq {
+    // path 标签修饰的 id 必须与请求路由中的片段对应，如
+    // id 在 service 语法块的请求路径上一定会有 :id 对应，见下文。
+    ID string `path:"id"`
+}
+
+type PathExampleResp {
+    Name string `json:"name"`
+}
+
+@server (
+    jwt:        Auth // 对当前 Foo 语法块下的所有路由，开启 jwt 认证，不需要则请删除此行
+    prefix:     /v1 // 对当前 Foo 语法块下的所有路由，新增 /v1 路由前缀，不需要则请删除此行
+    group:      g1 // 对当前 Foo 语法块下的所有路由，路由归并到 g1 目录下，不需要则请删除此行
+    timeout:    3s // 对当前 Foo 语法块下的所有路由进行超时配置，不需要则请删除此行
+    middleware: AuthInterceptor // 对当前 Foo 语法块下的所有路由添加中间件，不需要则请删除此行
+    maxBytes:   1048576 // 对当前 Foo 语法块下的所有路由添加请求体大小控制，单位为 byte,goctl 版本 >= 1.5.0 才支持
+)
+service Foo {
+    // 定义没有请求体和响应体的接口，如 ping
+    @handler ping
+    get /ping
+
+    // 定义只有请求体的接口，如更新信息
+    @handler update
+    post /update (UpdateReq)
+
+    // 定义只有响应体的结构，如获取全部信息列表
+    @handler list
+    get /list returns ([]ListItem)
+
+    // 定义有结构体和响应体的接口，如登录
+    @handler login
+    post /login (LoginReq) returns (LoginResp)
+
+    // 定义表单请求
+    @handler formExample
+    post /form/example (FormExampleReq)
+
+    // 定义 path 参数
+    @handler pathExample
+    get /path/example/:id (PathExampleReq) returns (PathExampleResp)
+}
+