doc-generate/example/example_respdoc.api

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 {
		Code    string `json:"code"`
		Message string `json:"message"`
		Details string `json:"details,omitempty"`
	}
	
	// 具體錯誤類型
	ValidationError {
		Code    string   `json:"code"`
		Message string   `json:"message"`
		Fields  []string `json:"fields"`
	}
	
	InsufficientStockError {
		Code      string `json:"code"`
		Message   string `json:"message"`
		ProductID string `json:"product_id"`
		Required  int    `json:"required"`
		Available int    `json:"available"`
	}
	
	InvalidPaymentError {
		Code    string `json:"code"`
		Message string `json:"message"`
		Method  string `json:"method"`
	}
	
	UnauthorizedError {
		Code    string `json:"code"`
		Message string `json:"message"`
		Reason  string `json:"reason"`
	}
)

@server (
	tags:    "query 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
	summary: "query 类型接口集合" // 对应 swagger 的 summary
	prefix: v1
	authType: apiKey // 指定该路由使用的鉴权类型，值为 securityDefinitionsFromJson 中定义的名称
	group:"demo"
)
service Swagger {
	@doc (
		description: "query 接口"
	)
	/*
    	@respdoc-201 (QueryResp) // 創建成功
    	@respdoc-400 (
        	300101: (ValidationError) 參數驗證失敗
        	300102: (InsufficientStockError) 庫存不足
        	300103: (InvalidPaymentError) 支付方式無效
    	) // 客戶端錯誤
    	@respdoc-401 (UnauthorizedError) // 未授權
    	@respdoc-500 (ErrorResponse) // 服務器錯誤
    */
	@handler query
	get /query (QueryReq) returns (QueryResp)
}