目标:实现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代码初始化