97 lines
5.1 KiB
Plaintext
97 lines
5.1 KiB
Plaintext
|
syntax = "v1"
|
|||
|
|
|
|||
|
|
info (
|
|||
|
|
title: "演示 API" // 对应 swagger 的 title
|
|||
|
|
description: "演示 api 生成 swagger 文件的 api 完整写法" // 对应 swagger 的 description
|
|||
|
|
version: "v1" // 对应 swagger 的 version
|
|||
|
|
termsOfService: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 termsOfService
|
|||
|
|
contactName: "keson.an" // 对应 swagger 的 contactName
|
|||
|
|
contactURL: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 contactURL
|
|||
|
|
contactEmail: "example@gmail.com" // 对应 swagger 的 contactEmail
|
|||
|
|
licenseName: "MIT" // 对应 swagger 的 licenseName
|
|||
|
|
licenseURL: "https://github.com/zeromicro/go-zero" // 对应 swagger 的 licenseURL
|
|||
|
|
consumes: "application/json" // 对应 swagger 的 consumes,不填默认为 application/json
|
|||
|
|
produces: "application/json" // 对应 swagger 的 produces,不填默认为 application/json
|
|||
|
|
schemes: "http,https" // 对应 swagger 的 schemes,不填默认为 https
|
|||
|
|
host: "example.com" // 对应 swagger 的 host,不填默认为 127.0.0.1
|
|||
|
|
basePath: "/v1" // 对应 swagger 的 basePath,不填默认为 /
|
|||
|
|
wrapCodeMsg: true // 是否用 code-msg 通用响应体，如果开启，则以格式 {"code":0,"msg":"OK","data":$data} 包括响应体
|
|||
|
|
bizCodeEnumDescription: "1001-未登录<br>1002-无权限操作" // 全局业务错误码枚举描述，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 时生效
|
|||
|
|
// securityDefinitionsFromJson 为自定义鉴权配置，json 内容将直接放入 swagger 的 securityDefinitions 中，
|
|||
|
|
// 格式参考 https://swagger.io/specification/v2/#security-definitions-object
|
|||
|
|
// 在 api 的 @server 中可声明 authType 来指定其路由使用的鉴权类型
|
|||
|
|
securityDefinitionsFromJson: `{"apiKey":{"description":"apiKey 类型鉴权自定义","type":"apiKey","name":"x-api-key","in":"header"}}`
|
|||
|
|
useDefinitions: true// 开启声明将生成models 进行关联，definitions 仅对响应体和 json 请求体生效
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
type (
|
|||
|
|
QueryReq {
|
|||
|
|
Id int `form:"id,range=[1:10000],example=10"`
|
|||
|
|
Name string `form:"name,example=keson.an"`
|
|||
|
|
Avatar string `form:"avatar,optional,example=https://example.com/avatar.png"`
|
|||
|
|
}
|
|||
|
|
QueryResp {
|
|||
|
|
Id int `json:"id,example=10"`
|
|||
|
|
Name string `json:"name,example=keson.an"`
|
|||
|
|
}
|
|||
|
|
// 錯誤響應
|
|||
|
|
ErrorResponse struct {
|
|||
|
|
Code string `json:"code" swagger:"description:錯誤代碼"`
|
|||
|
|
Message string `json:"message" swagger:"description:錯誤訊息"`
|
|||
|
|
Details string `json:"details,omitempty" swagger:"description:詳細信息"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 具體錯誤類型
|
|||
|
|
ValidationError struct {
|
|||
|
|
Code string `json:"code" swagger:"description:驗證錯誤代碼"`
|
|||
|
|
Message string `json:"message" swagger:"description:驗證錯誤訊息"`
|
|||
|
|
Fields []string `json:"fields" swagger:"description:錯誤字段列表"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
InsufficientStockError struct {
|
|||
|
|
Code string `json:"code" swagger:"description:庫存不足錯誤代碼"`
|
|||
|
|
Message string `json:"message" swagger:"description:庫存不足錯誤訊息"`
|
|||
|
|
ProductID string `json:"product_id" swagger:"description:商品ID"`
|
|||
|
|
Required int `json:"required" swagger:"description:需要數量"`
|
|||
|
|
Available int `json:"available" swagger:"description:可用數量"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
InvalidPaymentError struct {
|
|||
|
|
Code string `json:"code" swagger:"description:支付錯誤代碼"`
|
|||
|
|
Message string `json:"message" swagger:"description:支付錯誤訊息"`
|
|||
|
|
Method string `json:"method" swagger:"description:支付方式"`
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
UnauthorizedError struct {
|
|||
|
|
Code string `json:"code" swagger:"description:未授權錯誤代碼"`
|
|||
|
|
Message string `json:"message" swagger:"description:未授權錯誤訊息"`
|
|||
|
|
Reason string `json:"reason" swagger:"description:未授權原因"`
|
|||
|
|
}
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
@server (
|
|||
|
|
tags: "query 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
|
|||
|
|
summary: "query 类型接口集合" // 对应 swagger 的 summary
|
|||
|
|
prefix: v1
|
|||
|
|
authType: apiKey // 指定该路由使用的鉴权类型，值为 securityDefinitionsFromJson 中定义的名称
|
|||
|
|
group:"demo"
|
|||
|
|
)
|
|||
|
|
service Swagger {
|
|||
|
|
@doc (
|
|||
|
|
description: "query 接口"
|
|||
|
|
bizCodeEnumDescription: " 1003-用不存在<br>1004-非法操作" // 接口级别业务错误码枚举描述，会覆盖全局的业务错误码，json 格式,key 为业务错误码，value 为该错误码的描述，仅当 wrapCodeMsg 为 true 且 useDefinitions 为 false 时生效
|
|||
|
|
)
|
|||
|
|
/*
|
|||
|
|
@respdoc-201 (QueryResp) // 創建成功
|
|||
|
|
@respdoc-400 (
|
|||
|
|
300101: (ValidationError) 參數驗證失敗
|
|||
|
|
300102: (InsufficientStockError) 庫存不足
|
|||
|
|
300103: (InvalidPaymentError) 支付方式無效
|
|||
|
|
) // 客戶端錯誤
|
|||
|
|
@respdoc-401 (UnauthorizedError) // 未授權
|
|||
|
|
@respdoc-500 (ErrorResponse) // 服務器錯誤
|
|||
|
|
*/
|
|||
|
|
@handler query
|
|||
|
|
get /query (QueryReq) returns (QueryResp)
|
|||
|
|
}
|