photography/backend/api/desc/frontend/public.api

syntax = "v1"

import "common.api"

// 前端公共展示接口 - 无需认证

// 获取照片列表请求
type GetPublicPhotoListRequest {
    PageRequest
    CategoryId int64  `form:"category_id,optional"`
    Keyword    string `form:"keyword,optional"`
    Sort       string `form:"sort,optional,default=created_at_desc"` // created_at_desc, created_at_asc, title_asc, title_desc
}

// 获取照片列表响应
type GetPublicPhotoListResponse {
    BaseResponse
    Data PublicPhotoListData `json:"data"`
}

type PublicPhotoListData {
    PageResponse
    Photos []PublicPhoto `json:"photos"`
}

// 获取照片详情请求
type GetPublicPhotoRequest {
    Id int64 `path:"id"`
}

// 获取照片详情响应
type GetPublicPhotoResponse {
    BaseResponse
    Data PublicPhoto `json:"data"`
}

// 获取精选照片响应
type GetFeaturedPhotosResponse {
    BaseResponse
    Data []PublicPhoto `json:"data"`
}

// 获取最新照片请求
type GetRecentPhotosRequest {
    Limit int `form:"limit,optional,default=12"`
}

// 获取最新照片响应
type GetRecentPhotosResponse {
    BaseResponse
    Data []PublicPhoto `json:"data"`
}

// 获取分类列表响应
type GetPublicCategoryListResponse {
    BaseResponse
    Data []PublicCategory `json:"data"`
}

// 获取分类详情请求
type GetPublicCategoryRequest {
    Id int64 `path:"id"`
}

// 获取分类详情响应
type GetPublicCategoryResponse {
    BaseResponse
    Data PublicCategoryWithPhotos `json:"data"`
}

// 获取分类下的照片请求
type GetCategoryPhotosRequest {
    Id int64 `path:"id"`
    PageRequest
    Sort string `form:"sort,optional,default=created_at_desc"`
}

// 获取分类下的照片响应
type GetCategoryPhotosResponse {
    BaseResponse
    Data PublicPhotoListData `json:"data"`
}

// 前端公共接口组 - 无需认证
@server(
    group: public
    prefix: /api/v1/public
)
service photography-api {
    @doc "获取照片列表"
    @handler getPublicPhotoList
    get /photos (GetPublicPhotoListRequest) returns (GetPublicPhotoListResponse)
    
    @doc "获取照片详情"
    @handler getPublicPhoto
    get /photos/:id (GetPublicPhotoRequest) returns (GetPublicPhotoResponse)
    
    @doc "获取精选照片"
    @handler getFeaturedPhotos
    get /photos/featured returns (GetFeaturedPhotosResponse)
    
    @doc "获取最新照片"
    @handler getRecentPhotos
    get /photos/recent (GetRecentPhotosRequest) returns (GetRecentPhotosResponse)
    
    @doc "获取分类列表"
    @handler getPublicCategoryList
    get /categories returns (GetPublicCategoryListResponse)
    
    @doc "获取分类详情"
    @handler getPublicCategory
    get /categories/:id (GetPublicCategoryRequest) returns (GetPublicCategoryResponse)
    
    @doc "获取分类下的照片"
    @handler getCategoryPhotos
    get /categories/:id/photos (GetCategoryPhotosRequest) returns (GetCategoryPhotosResponse)
}