海鸥技术下午茶-wordpress站群搭建3api代码生成和swagger使用
目标:实现api编写和swagger使用
0.本次需要使用到的脚手架命令
生成 http server 代码
goctl api go -api all.api -dir ..
生成swagger文档
goctl api plugin -plugin goctl-swagger="swagger -filename station.json -host 127.0.0.1:8000" -api all.api -dir .
运行 swagger
swagger serve --no-open -F=swagger --port 36666 station.json
1.编写api
api详细文档
base.api api公共types
syntax = "v1"// The basic response with data | 基础带数据信息
type BaseDataInfo {Code int `json:"code"` // Error code | 错误代码Message string `json:"message"` // Message | 提示信息Data string `json:"data,omitempty"` // Data | 数据
}
// The basic response with data | 基础带数据信息
type BaseListInfo {Total uint64 `json:"total"` // The total number of data | 数据总数Data string `json:"data,omitempty"` // Data | 数据
}
// The basic response without data | 基础不带数据信息
type BaseMsgResp {Code int `json:"code"` // Error code | 错误代码Message string `json:"message"` // Message | 提示信息
}
// The page request parameters | 列表请求参数
type PageInfo {Page uint64 `form:"page" validate:"required,number,gt=0"` // Page number | 第几页PageSize uint64 `form:"pageSize" validate:"required,number,lt=100000"` // Page size | 单页数据行数
}
// Basic ID request | 基础ID参数请求
type IDReq {Id uint64 `json:"id" validate:"number"` // ID Required: true
}
// Basic IDs request | 基础ID数组参数请求
type IDsReq {Ids []uint64 `json:"ids"` // IDs Required: true
}
// Basic ID request | 基础ID地址参数请求
type IDPathReq {Id uint64 `path:"id"` // ID Required: true
}
all.api 用于聚合api
import "base.api"
import "./station/station.api"
import "./station/posts.api"
import "./station/delivery_log.api"
station.api 站点api
//站点信息
type (// Station StationInfo {Id uint64 `json:"id,optional"` // 主键DomainName string `json:"domainName"` // 域名Ip string `json:"ip,optional"` // 域名DomainYear int64 `json:"domainYear"` // 域名年份GoogleWeight float64 `json:"googleWeight"` // 谷歌权重Type string `json:"type"` // 网站类型Industry string `json:"industry"` // 网站行业ArticlesNum int64 `json:"articlesNum"` // 文章数量UserName string `json:"userName,optional"` // 账号名PassWord string `json:"passWord,optional"` // 密码}// Station 页面查询StationReq {PageInfoDomainName string `form:"domainName,optional"` // 域名Ip string `form:"ip,optional"` // ipDomainYear int64 `form:"domainYear,optional"` // 域名年份GoogleWeight string `form:"googleWeight,optional"` // 谷歌权重Type string `form:"type,optional"` // 网站类型Industry string `form:"industry,optional"` // 网站行业}// The response data of Station list | Station 列表数据StationListInfo {BaseListInfoData []StationInfo `json:"data"` // StationInfo list data | StationInfo列表数据}//Station 列表返回体StationListResp {BaseDataInfoData StationListInfo `json:"data"` // Station list data | Station列表数据}// Station 普通返回体StationInfoResp {BaseDataInfoData StationInfo `json:"data"` // Station information | Station数据}// Station Posts 返回体 StationPostsInfo {Id uint64 `json:"id"`Title string `json:"title"` // Title}// 返回体StationPostsResp{BaseDataInfoData []StationPostsInfo `json:"data"` // Station Posts 返回体}
)
@server (group: stationprefix: /stationtimeout: 10s
)
service Station {@doc "新增站点"@handler addStationpost /api/station (StationInfo) returns (StationInfoResp)@doc "修改站点"@handler updateStationput /api/station (StationInfo) returns (StationInfoResp)@doc "删除站点"@handler deleteStationdelete /api/station/:id (IDPathReq) returns (BaseDataInfo)@doc "查询站点"@handler queryStationget /api/station (StationReq) returns (StationListResp)@doc "获取关联的文章"@handler queryPostsget /api/station/posts/:id (IDPathReq) returns (StationPostsResp)
}
posts.api 文章api
//博客信息
type (// PostsPostsInfo {Id uint64 `json:"id,optional"`Title string `json:"title"` // 标题Source string `json:"source"` // 来源Author int64 `json:"author"` // 作者ThrownNum int64 `json:"thrownNum"` // 投放数量Categories string `json:"categories"` // 分类CreateTime string `json:"createTime,optional"` //时间Content string `json:"content"` //详情}// Posts 页面查询PostsReq {PageInfoTitle string `form:"title,optional"` // 标题Source string `form:"source,optional"` // 来源Categories string `form:"categories,optional"` // 分类Author int64 `form:"author,optional"` // 作者CreateTime int64 `form:"createTime,optional"` // 时间}// The response data of Posts list | Posts 列表数据PostsListInfo {BaseListInfoData []PostsInfo `json:"data"` // PostsInfo list data | PostsInfo列表数据}//Posts 列表返回体PostsListResp {BaseDataInfoData PostsListInfo `json:"data"` // Posts list data | Posts列表数据}// Posts 普通返回体PostsInfoResp {BaseDataInfoData PostsInfo `json:"data"` // Posts information | Posts数据}
)
@server (group: postsprefix: /station
)
service Station {@doc "新增Posts"@handler addPostspost /api/posts (PostsInfo) returns (PostsInfoResp)@doc "修改Posts"@handler updatePostsput /api/posts (PostsInfo) returns (PostsInfoResp)@doc "删除Posts"@handler deletePostsdelete /api/posts/:id (IDPathReq) returns (BaseDataInfo)@doc "查询Posts"@handler queryPostsget /api/posts (PostsReq) returns (PostsListResp)@doc "查询Posts详情"@handler getPostsget /api/posts/:id (IDPathReq) returns (PostsInfoResp)
}
delivery_log.api 文章分发日志api
//博客信息
type (// DeliveryLogDeliveryLogInfo {Id uint64 `json:"id,optional"`Title string `json:"title"` // 标题Source string `json:"source,optional"` // 来源DomainName string `json:"domainName"` // 域名DeliveryDate string `json:"deliveryDate,optional"` // 投放日期Deliverer string `json:"deliverer,optional"` // 投放人Status int64 `json:"status,optional"` // 投放状态Author uint64 `json:"author,optional"` // 作者WpCateIds string `json:"wpCateIds,optional"` // wp分类StationId uint64 `json:"stationId,optional"` // 站点idPostsId uint64 `json:"postsId,optional"` // 文章id}// 投放对象DeliveryInfo {StationInfoList []StationInfo `json:"stationInfoList"` // 站点idPostsInfoList []PostsInfo `json:"postsInfoList"` // 文章id}// DeliveryLog 页面查询DeliveryLogReq {PageInfoTitle string `form:"title,optional"` // 标题Source string `form:"source,optional"` // 来源DomainName string `form:"domainName,optional"` // 域名DeliveryDate int64 `form:"deliveryDate,optional"` // 投放日期Deliverer string `form:"deliverer,optional"` // 投放人Status int64 `form:"status,optional"` // 投放状态Author uint64 `form:"author,optional"` // 作者}// The response data of DeliveryLog list | DeliveryLog 列表数据DeliveryLogListInfo {BaseListInfoData []DeliveryLogInfo `json:"data"` // DeliveryLogInfo list data | DeliveryLogInfo列表数据}// The response data of DeliveryLog list | DeliveryLog 列表数据DeliveryListInfo {Data []DeliveryLogInfo `json:"data"` // DeliveryInfo list data | DeliveryInfo列表数据}//DeliveryLog 列表返回体DeliveryLogListResp {BaseDataInfoData DeliveryLogListInfo `json:"data"` // DeliveryLog list data | DeliveryLog列表数据}// DeliveryLog 普通返回体DeliveryLogInfoResp {BaseDataInfoData DeliveryLogInfo `json:"data"` // DeliveryLog information | DeliveryLog数据}
)@server (group: deliveryLogprefix: /station
)
service Station {@doc "投放" @handler addDeliveryLogpost /api/deliverylog (DeliveryListInfo) returns (BaseDataInfo)@doc "修改DeliveryLog"@handler updateDeliveryLogput /api/deliverylog (DeliveryLogInfo) returns (DeliveryLogInfoResp)@doc "删除DeliveryLog"@handler deleteDeliveryLogdelete /api/deliverylog/:id (IDPathReq) returns (BaseDataInfo)@doc "查询DeliveryLog"@handler queryDeliveryLogget /api/deliverylog (DeliveryLogReq) returns (DeliveryLogListResp)@doc "获取投放列表"@handler generateDeliveryListpost /api/deliverylog/list (DeliveryInfo) returns (DeliveryLogListResp)
}
2.生成代码
进入到api项目的desc目录，运行生成api代码脚手架命令
cd ./desc
goctl api go -api all.api -dir ..
3.swagger使用
还是在desc目录下，生成swaagger json
goctl api plugin -plugin goctl-swagger="swagger -filename station.json -host 127.0.0.1:8000" -api all.api -dir .
运行swagger
swagger serve --no-open -F=swagger --port 36666 station.json
4.允许跨域配置
在入口文件 station.go中修改
//rest.MustNewServer(c.RestConf)
//修改为下面的代码
rest.MustNewServer(c.RestConf, rest.WithCors())
5.测试api
运行rpc和api后。
启动完swagger，我们可以在swagger上面进行api测试了。
访问 http://127.0.0.1:36666/docs 页面，可以直接在页面上进行测试。
项目源码地址
上一篇: wordpress站群搭建2代码初始化
