update
This commit is contained in:
228
api/Blog.api
Normal file
228
api/Blog.api
Normal file
@@ -0,0 +1,228 @@
|
||||
syntax = "v1"
|
||||
|
||||
info (
|
||||
title: "Blog API"
|
||||
desc: "Blog service API with file upload/download and CRUD operations"
|
||||
author: "cialloo"
|
||||
date: "2025-10-22"
|
||||
version: "v1"
|
||||
)
|
||||
|
||||
// ============= File Upload/Download Types =============
|
||||
type (
|
||||
// Request for generating presigned upload URL
|
||||
GenerateUploadUrlReq {
|
||||
FileName string `json:"file_name"` // Original file name
|
||||
FileSize int64 `json:"file_size"` // File size in bytes
|
||||
}
|
||||
|
||||
GenerateUploadUrlResp {
|
||||
FileId int64 `json:"file_id"` // Generated file ID
|
||||
PresignedUrl string `json:"presigned_url"` // S3 presigned upload URL
|
||||
FileKey string `json:"file_key"` // S3 file key
|
||||
ExpiresIn int `json:"expires_in"` // URL expiration time in seconds
|
||||
}
|
||||
|
||||
// Request for generating presigned download URL
|
||||
GenerateDownloadUrlReq {
|
||||
FileId int64 `path:"file_id"` // File ID to download
|
||||
}
|
||||
|
||||
GenerateDownloadUrlResp {
|
||||
FileName string `json:"file_name"` // Original file name
|
||||
PresignedUrl string `json:"presigned_url"` // S3 presigned download URL
|
||||
FileSize int64 `json:"file_size"` // File size in bytes
|
||||
ExpiresIn int `json:"expires_in"` // URL expiration time in seconds
|
||||
}
|
||||
|
||||
// Confirm upload completion
|
||||
ConfirmUploadReq {
|
||||
FileId int64 `json:"file_id"` // File ID to confirm
|
||||
}
|
||||
|
||||
ConfirmUploadResp {
|
||||
Success bool `json:"success"` // Upload confirmation status
|
||||
Message string `json:"message"` // Status message
|
||||
}
|
||||
)
|
||||
|
||||
// ============= Post Types =============
|
||||
type (
|
||||
// Create post request
|
||||
CreatePostReq {
|
||||
Title string `json:"title"` // Post title
|
||||
Content string `json:"content"` // Post content
|
||||
Hashtags []string `json:"hashtags,optional"` // Associated hashtags
|
||||
}
|
||||
|
||||
CreatePostResp {
|
||||
PostId int64 `json:"post_id"` // Created post ID
|
||||
}
|
||||
|
||||
// Update post request
|
||||
UpdatePostReq {
|
||||
PostId int64 `path:"post_id"` // Post ID to update
|
||||
Title string `json:"title,optional"` // New title
|
||||
Content string `json:"content,optional"` // New content
|
||||
Hashtags []string `json:"hashtags,optional"` // New hashtags (replaces all)
|
||||
}
|
||||
|
||||
UpdatePostResp {
|
||||
Success bool `json:"success"` // Update status
|
||||
}
|
||||
|
||||
// Delete post request
|
||||
DeletePostReq {
|
||||
PostId int64 `path:"post_id"` // Post ID to delete
|
||||
}
|
||||
|
||||
DeletePostResp {
|
||||
Success bool `json:"success"` // Delete status
|
||||
}
|
||||
|
||||
// Get post detail request
|
||||
GetPostReq {
|
||||
PostId int64 `path:"post_id"` // Post ID to retrieve
|
||||
}
|
||||
|
||||
PostDetail {
|
||||
PostId int64 `json:"post_id"` // Post ID
|
||||
Title string `json:"title"` // Post title
|
||||
Content string `json:"content"` // Post content
|
||||
ViewCount int64 `json:"view_count"` // View count
|
||||
Hashtags []Hashtag `json:"hashtags"` // Associated hashtags
|
||||
CreatedAt string `json:"created_at"` // Creation timestamp
|
||||
UpdatedAt string `json:"updated_at"` // Last update timestamp
|
||||
}
|
||||
|
||||
GetPostResp {
|
||||
Post PostDetail `json:"post"` // Post detail
|
||||
}
|
||||
|
||||
// List posts request
|
||||
ListPostsReq {
|
||||
Page int `form:"page,default=1"` // Page number
|
||||
PageSize int `form:"page_size,default=10"` // Items per page
|
||||
Hashtag string `form:"hashtag,optional"` // Filter by hashtag name
|
||||
SortBy string `form:"sort_by,default=created_at,options=created_at|view_count|updated_at"` // Sort field
|
||||
}
|
||||
|
||||
PostItem {
|
||||
PostId int64 `json:"post_id"` // Post ID
|
||||
Title string `json:"title"` // Post title
|
||||
ViewCount int64 `json:"view_count"` // View count
|
||||
Hashtags []Hashtag `json:"hashtags"` // Associated hashtags
|
||||
CreatedAt string `json:"created_at"` // Creation timestamp
|
||||
UpdatedAt string `json:"updated_at"` // Last update timestamp
|
||||
}
|
||||
|
||||
ListPostsResp {
|
||||
Posts []PostItem `json:"posts"` // List of posts
|
||||
Total int64 `json:"total"` // Total count
|
||||
Page int `json:"page"` // Current page
|
||||
PageSize int `json:"page_size"` // Items per page
|
||||
TotalPages int `json:"total_pages"` // Total pages
|
||||
}
|
||||
)
|
||||
|
||||
// ============= Hashtag Types =============
|
||||
type (
|
||||
Hashtag {
|
||||
HashtagId int64 `json:"hashtag_id"` // Hashtag ID
|
||||
Name string `json:"name"` // Hashtag name
|
||||
UsageCount int64 `json:"usage_count"` // Usage count
|
||||
}
|
||||
|
||||
// List hashtags request
|
||||
ListHashtagsReq {
|
||||
Page int `form:"page,default=1"` // Page number
|
||||
PageSize int `form:"page_size,default=20"` // Items per page
|
||||
SortBy string `form:"sort_by,default=usage_count,options=usage_count|created_at|name"` // Sort field
|
||||
}
|
||||
|
||||
ListHashtagsResp {
|
||||
Hashtags []Hashtag `json:"hashtags"` // List of hashtags
|
||||
Total int64 `json:"total"` // Total count
|
||||
Page int `json:"page"` // Current page
|
||||
PageSize int `json:"page_size"` // Items per page
|
||||
TotalPages int `json:"total_pages"` // Total pages
|
||||
}
|
||||
|
||||
// Get popular hashtags
|
||||
GetPopularHashtagsReq {
|
||||
Limit int `form:"limit,default=10"` // Number of hashtags to return
|
||||
}
|
||||
|
||||
GetPopularHashtagsResp {
|
||||
Hashtags []Hashtag `json:"hashtags"` // Popular hashtags
|
||||
}
|
||||
)
|
||||
|
||||
// ============= Service Definition =============
|
||||
@server (
|
||||
prefix: /api/v1/blog
|
||||
group: file
|
||||
)
|
||||
service Blog {
|
||||
@doc "Generate presigned URL for file upload"
|
||||
@handler generateUploadUrl
|
||||
post /files/upload/url (GenerateUploadUrlReq) returns (GenerateUploadUrlResp)
|
||||
|
||||
@doc "Generate presigned URL for file download"
|
||||
@handler generateDownloadUrl
|
||||
get /files/download/:file_id (GenerateDownloadUrlReq) returns (GenerateDownloadUrlResp)
|
||||
|
||||
@doc "Confirm file upload completion"
|
||||
@handler confirmUpload
|
||||
post /files/upload/confirm (ConfirmUploadReq) returns (ConfirmUploadResp)
|
||||
}
|
||||
|
||||
@server (
|
||||
prefix: /api/v1/blog
|
||||
group: post
|
||||
)
|
||||
service Blog {
|
||||
@doc "Create a new blog post"
|
||||
@handler createPost
|
||||
post /posts (CreatePostReq) returns (CreatePostResp)
|
||||
|
||||
@doc "Update an existing blog post"
|
||||
@handler updatePost
|
||||
put /posts/:post_id (UpdatePostReq) returns (UpdatePostResp)
|
||||
|
||||
@doc "Delete a blog post"
|
||||
@handler deletePost
|
||||
delete /posts/:post_id (DeletePostReq) returns (DeletePostResp)
|
||||
|
||||
@doc "Get blog post detail"
|
||||
@handler getPost
|
||||
get /posts/:post_id (GetPostReq) returns (GetPostResp)
|
||||
|
||||
@doc "List blog posts with pagination and filtering"
|
||||
@handler listPosts
|
||||
get /posts (ListPostsReq) returns (ListPostsResp)
|
||||
}
|
||||
|
||||
@server (
|
||||
prefix: /api/v1/blog
|
||||
group: hashtag
|
||||
)
|
||||
service Blog {
|
||||
@doc "List all hashtags with pagination"
|
||||
@handler listHashtags
|
||||
get /hashtags (ListHashtagsReq) returns (ListHashtagsResp)
|
||||
|
||||
@doc "Get popular hashtags"
|
||||
@handler getPopularHashtags
|
||||
get /hashtags/popular (GetPopularHashtagsReq) returns (GetPopularHashtagsResp)
|
||||
}
|
||||
|
||||
@server (
|
||||
prefix: /api/v1/blog
|
||||
group: common
|
||||
)
|
||||
service Blog {
|
||||
@doc "Health check endpoint"
|
||||
@handler ping
|
||||
get /ping
|
||||
}
|
||||
75
api/example.api
Normal file
75
api/example.api
Normal file
@@ -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)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user