mirror of
https://github.com/zeromicro/go-zero.git
synced 2026-05-10 16:30:01 +08:00
feature/goctl-api-swagger (#4780)
This commit is contained in:
kesonan
4
tools/goctl/api/swagger/example/.gitignore
vendored
Normal file
4
tools/goctl/api/swagger/example/.gitignore
vendored
Normal file
@@ -0,0 +1,4 @@
|
||||
*.json
|
||||
*.yaml
|
||||
bin
|
||||
output
|
||||
234
tools/goctl/api/swagger/example/example.api
Normal file
234
tools/goctl/api/swagger/example/example.api
Normal file
@@ -0,0 +1,234 @@
|
||||
syntax = "v1"
|
||||
|
||||
info (
|
||||
title: "Demo API" // title corresponding to Swagger
|
||||
description: "Generating Swagger files using the API demo." // description corresponding to Swagger
|
||||
version: "v1" // version corresponding to Swagger
|
||||
termsOfService: "https://github.com/zeromicro/go-zero" // termsOfService corresponding to Swagger
|
||||
contactName: "keson.an" // contactName corresponding to Swagger
|
||||
contactURL: "https://github.com/zeromicro/go-zero" // contactURL corresponding to Swagger
|
||||
contactEmail: "example@gmail.com" // contactEmail corresponding to Swagger
|
||||
licenseName: "MIT" // licenseName corresponding to Swagger
|
||||
licenseURL: "https://github.com/zeromicro/go-zero" // licenseURL corresponding to Swagger
|
||||
consumes: "application/json" // consumes corresponding to Swagger,default value is `application/json`
|
||||
produces: "application/json" // produces corresponding to Swagger,default value is `application/json`
|
||||
schemes: "https" // schemes corresponding to Swagger,default value is `https``
|
||||
host: "example.com" // host corresponding to Swagger,default value is `127.0.0.1`
|
||||
basePath: "/v1" // basePath corresponding to Swagger,default value is `/`
|
||||
wrapCodeMsg: "true" // to wrap in the universal code-msg structure, like {"code":0,"msg":"OK","data":$data}
|
||||
bizCodeEnumDescription: "1001-User not login<br>1002-User permission denied" // enums of business error codes, in JSON format, with the key being the business error code and the value being the description of that error code. This only takes effect when wrapCodeMsg is set to true.
|
||||
)
|
||||
|
||||
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"`
|
||||
}
|
||||
PathQueryReq {
|
||||
Id int `path:"id,range=[1:10000],example=10"`
|
||||
Name string `form:"name,example=keson.an"`
|
||||
}
|
||||
PathQueryResp {
|
||||
Id int `json:"id,example=10"`
|
||||
Name string `json:"name,example=keson.an"`
|
||||
}
|
||||
)
|
||||
|
||||
@server (
|
||||
tags: "query" // tags corresponding to Swagger
|
||||
summary: "query API set" // summary corresponding to Swagger
|
||||
)
|
||||
service Swagger {
|
||||
@doc (
|
||||
description: "query demo"
|
||||
)
|
||||
@handler query
|
||||
get /query (QueryReq) returns (QueryResp)
|
||||
|
||||
@doc (
|
||||
description: "show path query demo"
|
||||
)
|
||||
@handler queryPath
|
||||
get /query/:id (PathQueryReq) returns (PathQueryResp)
|
||||
}
|
||||
|
||||
type (
|
||||
FormReq {
|
||||
Id int `form:"id,range=[1:10000],example=10"`
|
||||
Name string `form:"name,example=keson.an"`
|
||||
}
|
||||
FormResp {
|
||||
Id int `json:"id,example=10"`
|
||||
Name string `json:"name,example=keson.an"`
|
||||
}
|
||||
)
|
||||
|
||||
@server (
|
||||
tags: "form" // tags corresponding to Swagger
|
||||
summary: "form API set" // summary corresponding to Swagger
|
||||
)
|
||||
service Swagger {
|
||||
@doc (
|
||||
description: "form demo"
|
||||
)
|
||||
@handler form
|
||||
post /form (FormReq) returns (FormResp)
|
||||
}
|
||||
|
||||
type (
|
||||
JsonReq {
|
||||
Id int `json:"id,range=[1:10000],example=10"`
|
||||
Name string `json:"name,example=keson.an"`
|
||||
Avatar string `json:"avatar,optional"`
|
||||
Language string `json:"language,options=golang|java|python|typescript|rust"`
|
||||
Gender string `json:"gender,default=male,options=male|female,example=male"`
|
||||
}
|
||||
JsonResp {
|
||||
Id int `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Avatar string `json:"avatar"`
|
||||
Language string `json:"language"`
|
||||
Gender string `json:"gender"`
|
||||
}
|
||||
ComplexJsonLevel2 {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
}
|
||||
ComplexJsonLevel1 {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
// Object
|
||||
Object ComplexJsonLevel2 `json:"object"`
|
||||
PointerObject *ComplexJsonLevel2 `json:"pointerObject"`
|
||||
}
|
||||
ComplexJsonReq {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
// basic array
|
||||
ArrayInteger []int `json:"arrayInteger"`
|
||||
ArrayNumber []float64 `json:"arrayNumber"`
|
||||
ArrayBoolean []bool `json:"arrayBoolean"`
|
||||
ArrayString []string `json:"arrayString"`
|
||||
// basic array array
|
||||
ArrayArrayInteger [][]int `json:"arrayArrayInteger"`
|
||||
ArrayArrayNumber [][]float64 `json:"arrayArrayNumber"`
|
||||
ArrayArrayBoolean [][]bool `json:"arrayArrayBoolean"`
|
||||
ArrayArrayString [][]string `json:"arrayArrayString"`
|
||||
// basic map
|
||||
MapInteger map[string]int `json:"mapInteger"`
|
||||
MapNumber map[string]float64 `json:"mapNumber"`
|
||||
MapBoolean map[string]bool `json:"mapBoolean"`
|
||||
MapString map[string]string `json:"mapString"`
|
||||
// basic map array
|
||||
MapArrayInteger map[string][]int `json:"mapArrayInteger"`
|
||||
MapArrayNumber map[string][]float64 `json:"mapArrayNumber"`
|
||||
MapArrayBoolean map[string][]bool `json:"mapArrayBoolean"`
|
||||
MapArrayString map[string][]string `json:"mapArrayString"`
|
||||
// basic map map
|
||||
MapMapInteger map[string]map[string]int `json:"mapMapInteger"`
|
||||
MapMapNumber map[string]map[string]float64 `json:"mapMapNumber"`
|
||||
MapMapBoolean map[string]map[string]bool `json:"mapMapBoolean"`
|
||||
MapMapString map[string]map[string]string `json:"mapMapString"`
|
||||
// Object
|
||||
Object ComplexJsonLevel1 `json:"object"`
|
||||
PointerObject *ComplexJsonLevel1 `json:"pointerObject"`
|
||||
// Object array
|
||||
ArrayObject []ComplexJsonLevel1 `json:"arrayObject"`
|
||||
ArrayPointerObject []*ComplexJsonLevel1 `json:"arrayPointerObject"`
|
||||
// Object map
|
||||
MapObject map[string]ComplexJsonLevel1 `json:"mapObject"`
|
||||
MapPointerObject map[string]*ComplexJsonLevel1 `json:"mapPointerObject"`
|
||||
// Object array array
|
||||
ArrayArrayObject [][]ComplexJsonLevel1 `json:"arrayArrayObject"`
|
||||
ArrayArrayPointerObject [][]*ComplexJsonLevel1 `json:"arrayArrayPointerObject"`
|
||||
// Object array map
|
||||
ArrayMapObject []map[string]ComplexJsonLevel1 `json:"arrayMapObject"`
|
||||
ArrayMapPointerObject []map[string]*ComplexJsonLevel1 `json:"arrayMapPointerObject"`
|
||||
// Object map array
|
||||
MapArrayObject map[string][]ComplexJsonLevel1 `json:"mapArrayObject"`
|
||||
MapArrayPointerObject map[string][]*ComplexJsonLevel1 `json:"mapArrayPointerObject"`
|
||||
}
|
||||
ComplexJsonResp {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
// basic array
|
||||
ArrayInteger []int `json:"arrayInteger"`
|
||||
ArrayNumber []float64 `json:"arrayNumber"`
|
||||
ArrayBoolean []bool `json:"arrayBoolean"`
|
||||
ArrayString []string `json:"arrayString"`
|
||||
// basic array array
|
||||
ArrayArrayInteger [][]int `json:"arrayArrayInteger"`
|
||||
ArrayArrayNumber [][]float64 `json:"arrayArrayNumber"`
|
||||
ArrayArrayBoolean [][]bool `json:"arrayArrayBoolean"`
|
||||
ArrayArrayString [][]string `json:"arrayArrayString"`
|
||||
// basic map
|
||||
MapInteger map[string]int `json:"mapInteger"`
|
||||
MapNumber map[string]float64 `json:"mapNumber"`
|
||||
MapBoolean map[string]bool `json:"mapBoolean"`
|
||||
MapString map[string]string `json:"mapString"`
|
||||
// basic map array
|
||||
MapArrayInteger map[string][]int `json:"mapArrayInteger"`
|
||||
MapArrayNumber map[string][]float64 `json:"mapArrayNumber"`
|
||||
MapArrayBoolean map[string][]bool `json:"mapArrayBoolean"`
|
||||
MapArrayString map[string][]string `json:"mapArrayString"`
|
||||
// basic map map
|
||||
MapMapInteger map[string]map[string]int `json:"mapMapInteger"`
|
||||
MapMapNumber map[string]map[string]float64 `json:"mapMapNumber"`
|
||||
MapMapBoolean map[string]map[string]bool `json:"mapMapBoolean"`
|
||||
MapMapString map[string]map[string]string `json:"mapMapString"`
|
||||
// Object
|
||||
Object ComplexJsonLevel1 `json:"object"`
|
||||
PointerObject *ComplexJsonLevel1 `json:"pointerObject"`
|
||||
// Object array
|
||||
ArrayObject []ComplexJsonLevel1 `json:"arrayObject"`
|
||||
ArrayPointerObject []*ComplexJsonLevel1 `json:"arrayPointerObject"`
|
||||
// Object map
|
||||
MapObject map[string]ComplexJsonLevel1 `json:"mapObject"`
|
||||
MapPointerObject map[string]*ComplexJsonLevel1 `json:"mapPointerObject"`
|
||||
// Object array array
|
||||
ArrayArrayObject [][]ComplexJsonLevel1 `json:"arrayArrayObject"`
|
||||
ArrayArrayPointerObject [][]*ComplexJsonLevel1 `json:"arrayArrayPointerObject"`
|
||||
// Object array map
|
||||
ArrayMapObject []map[string]ComplexJsonLevel1 `json:"arrayMapObject"`
|
||||
ArrayMapPointerObject []map[string]*ComplexJsonLevel1 `json:"arrayMapPointerObject"`
|
||||
// Object map array
|
||||
MapArrayObject map[string][]ComplexJsonLevel1 `json:"mapArrayObject"`
|
||||
MapArrayPointerObject map[string][]*ComplexJsonLevel1 `json:"mapArrayPointerObject"`
|
||||
}
|
||||
)
|
||||
|
||||
@server (
|
||||
tags: "postJson" // tags corresponding to Swagger
|
||||
summary: "json API set" // summary corresponding to Swagger
|
||||
)
|
||||
service Swagger {
|
||||
@doc (
|
||||
description: "simple json request body API"
|
||||
)
|
||||
@handler jsonSimple
|
||||
post /json/simple (JsonReq) returns (JsonResp)
|
||||
|
||||
@doc (
|
||||
description: "complex json request body API"
|
||||
)
|
||||
@handler jsonComplex
|
||||
post /json/complex (ComplexJsonReq) returns (ComplexJsonResp)
|
||||
}
|
||||
|
||||
235
tools/goctl/api/swagger/example/example_cn.api
Normal file
235
tools/goctl/api/swagger/example/example_cn.api
Normal file
@@ -0,0 +1,235 @@
|
||||
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: "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 时生效
|
||||
)
|
||||
|
||||
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"`
|
||||
}
|
||||
PathQueryReq {
|
||||
Id int `path:"id,range=[1:10000],example=10"`
|
||||
Name string `form:"name,example=keson.an"`
|
||||
}
|
||||
PathQueryResp {
|
||||
Id int `json:"id,example=10"`
|
||||
Name string `json:"name,example=keson.an"`
|
||||
}
|
||||
)
|
||||
|
||||
@server (
|
||||
tags: "query 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
|
||||
summary: "query 类型接口集合" // 对应 swagger 的 summary
|
||||
prefix: v1
|
||||
)
|
||||
service Swagger {
|
||||
@doc (
|
||||
description: "query 接口"
|
||||
)
|
||||
@handler query
|
||||
get /query (QueryReq) returns (QueryResp)
|
||||
|
||||
@doc (
|
||||
description: "query path 中包含 id 字段接口"
|
||||
)
|
||||
@handler queryPath
|
||||
get /query/:id (PathQueryReq) returns (PathQueryResp)
|
||||
}
|
||||
|
||||
type (
|
||||
FormReq {
|
||||
Id int `form:"id,range=[1:10000],example=10"`
|
||||
Name string `form:"name,example=keson.an"`
|
||||
}
|
||||
FormResp {
|
||||
Id int `json:"id,example=10"`
|
||||
Name string `json:"name,example=keson.an"`
|
||||
}
|
||||
)
|
||||
|
||||
@server (
|
||||
tags: "form 表单 api 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
|
||||
summary: "form 表单类型接口集合" // 对应 swagger 的 summary
|
||||
)
|
||||
service Swagger {
|
||||
@doc (
|
||||
description: "form 接口"
|
||||
)
|
||||
@handler form
|
||||
post /form (FormReq) returns (FormResp)
|
||||
}
|
||||
|
||||
type (
|
||||
JsonReq {
|
||||
Id int `json:"id,range=[1:10000],example=10"`
|
||||
Name string `json:"name,example=keson.an"`
|
||||
Avatar string `json:"avatar,optional"`
|
||||
Language string `json:"language,options=golang|java|python|typescript|rust"`
|
||||
Gender string `json:"gender,default=male,options=male|female,example=male"`
|
||||
}
|
||||
JsonResp {
|
||||
Id int `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Avatar string `json:"avatar"`
|
||||
Language string `json:"language"`
|
||||
Gender string `json:"gender"`
|
||||
}
|
||||
ComplexJsonLevel2 {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
}
|
||||
ComplexJsonLevel1 {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
// Object
|
||||
Object ComplexJsonLevel2 `json:"object"`
|
||||
PointerObject *ComplexJsonLevel2 `json:"pointerObject"`
|
||||
}
|
||||
ComplexJsonReq {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
// basic array
|
||||
ArrayInteger []int `json:"arrayInteger"`
|
||||
ArrayNumber []float64 `json:"arrayNumber"`
|
||||
ArrayBoolean []bool `json:"arrayBoolean"`
|
||||
ArrayString []string `json:"arrayString"`
|
||||
// basic array array
|
||||
ArrayArrayInteger [][]int `json:"arrayArrayInteger"`
|
||||
ArrayArrayNumber [][]float64 `json:"arrayArrayNumber"`
|
||||
ArrayArrayBoolean [][]bool `json:"arrayArrayBoolean"`
|
||||
ArrayArrayString [][]string `json:"arrayArrayString"`
|
||||
// basic map
|
||||
MapInteger map[string]int `json:"mapInteger"`
|
||||
MapNumber map[string]float64 `json:"mapNumber"`
|
||||
MapBoolean map[string]bool `json:"mapBoolean"`
|
||||
MapString map[string]string `json:"mapString"`
|
||||
// basic map array
|
||||
MapArrayInteger map[string][]int `json:"mapArrayInteger"`
|
||||
MapArrayNumber map[string][]float64 `json:"mapArrayNumber"`
|
||||
MapArrayBoolean map[string][]bool `json:"mapArrayBoolean"`
|
||||
MapArrayString map[string][]string `json:"mapArrayString"`
|
||||
// basic map map
|
||||
MapMapInteger map[string]map[string]int `json:"mapMapInteger"`
|
||||
MapMapNumber map[string]map[string]float64 `json:"mapMapNumber"`
|
||||
MapMapBoolean map[string]map[string]bool `json:"mapMapBoolean"`
|
||||
MapMapString map[string]map[string]string `json:"mapMapString"`
|
||||
// Object
|
||||
Object ComplexJsonLevel1 `json:"object"`
|
||||
PointerObject *ComplexJsonLevel1 `json:"pointerObject"`
|
||||
// Object array
|
||||
ArrayObject []ComplexJsonLevel1 `json:"arrayObject"`
|
||||
ArrayPointerObject []*ComplexJsonLevel1 `json:"arrayPointerObject"`
|
||||
// Object map
|
||||
MapObject map[string]ComplexJsonLevel1 `json:"mapObject"`
|
||||
MapPointerObject map[string]*ComplexJsonLevel1 `json:"mapPointerObject"`
|
||||
// Object array array
|
||||
ArrayArrayObject [][]ComplexJsonLevel1 `json:"arrayArrayObject"`
|
||||
ArrayArrayPointerObject [][]*ComplexJsonLevel1 `json:"arrayArrayPointerObject"`
|
||||
// Object array map
|
||||
ArrayMapObject []map[string]ComplexJsonLevel1 `json:"arrayMapObject"`
|
||||
ArrayMapPointerObject []map[string]*ComplexJsonLevel1 `json:"arrayMapPointerObject"`
|
||||
// Object map array
|
||||
MapArrayObject map[string][]ComplexJsonLevel1 `json:"mapArrayObject"`
|
||||
MapArrayPointerObject map[string][]*ComplexJsonLevel1 `json:"mapArrayPointerObject"`
|
||||
}
|
||||
ComplexJsonResp {
|
||||
// basic
|
||||
Integer int `json:"integer,example=1"`
|
||||
Number float64 `json:"number,example=1.1"`
|
||||
Boolean bool `json:"boolean,options=true|false,example=true"`
|
||||
String string `json:"string,example=some text"`
|
||||
// basic array
|
||||
ArrayInteger []int `json:"arrayInteger"`
|
||||
ArrayNumber []float64 `json:"arrayNumber"`
|
||||
ArrayBoolean []bool `json:"arrayBoolean"`
|
||||
ArrayString []string `json:"arrayString"`
|
||||
// basic array array
|
||||
ArrayArrayInteger [][]int `json:"arrayArrayInteger"`
|
||||
ArrayArrayNumber [][]float64 `json:"arrayArrayNumber"`
|
||||
ArrayArrayBoolean [][]bool `json:"arrayArrayBoolean"`
|
||||
ArrayArrayString [][]string `json:"arrayArrayString"`
|
||||
// basic map
|
||||
MapInteger map[string]int `json:"mapInteger"`
|
||||
MapNumber map[string]float64 `json:"mapNumber"`
|
||||
MapBoolean map[string]bool `json:"mapBoolean"`
|
||||
MapString map[string]string `json:"mapString"`
|
||||
// basic map array
|
||||
MapArrayInteger map[string][]int `json:"mapArrayInteger"`
|
||||
MapArrayNumber map[string][]float64 `json:"mapArrayNumber"`
|
||||
MapArrayBoolean map[string][]bool `json:"mapArrayBoolean"`
|
||||
MapArrayString map[string][]string `json:"mapArrayString"`
|
||||
// basic map map
|
||||
MapMapInteger map[string]map[string]int `json:"mapMapInteger"`
|
||||
MapMapNumber map[string]map[string]float64 `json:"mapMapNumber"`
|
||||
MapMapBoolean map[string]map[string]bool `json:"mapMapBoolean"`
|
||||
MapMapString map[string]map[string]string `json:"mapMapString"`
|
||||
// Object
|
||||
Object ComplexJsonLevel1 `json:"object"`
|
||||
PointerObject *ComplexJsonLevel1 `json:"pointerObject"`
|
||||
// Object array
|
||||
ArrayObject []ComplexJsonLevel1 `json:"arrayObject"`
|
||||
ArrayPointerObject []*ComplexJsonLevel1 `json:"arrayPointerObject"`
|
||||
// Object map
|
||||
MapObject map[string]ComplexJsonLevel1 `json:"mapObject"`
|
||||
MapPointerObject map[string]*ComplexJsonLevel1 `json:"mapPointerObject"`
|
||||
// Object array array
|
||||
ArrayArrayObject [][]ComplexJsonLevel1 `json:"arrayArrayObject"`
|
||||
ArrayArrayPointerObject [][]*ComplexJsonLevel1 `json:"arrayArrayPointerObject"`
|
||||
// Object array map
|
||||
ArrayMapObject []map[string]ComplexJsonLevel1 `json:"arrayMapObject"`
|
||||
ArrayMapPointerObject []map[string]*ComplexJsonLevel1 `json:"arrayMapPointerObject"`
|
||||
// Object map array
|
||||
MapArrayObject map[string][]ComplexJsonLevel1 `json:"mapArrayObject"`
|
||||
MapArrayPointerObject map[string][]*ComplexJsonLevel1 `json:"mapArrayPointerObject"`
|
||||
}
|
||||
)
|
||||
|
||||
@server (
|
||||
tags: "post json api 演示" // 对应 swagger 的 tags,可以对 swagger 中的 api 进行分组
|
||||
summary: "json 请求类型接口集合" // 对应 swagger 的 summary
|
||||
)
|
||||
service Swagger {
|
||||
@doc (
|
||||
description: "简单的 json 请求体接口"
|
||||
)
|
||||
@handler jsonSimple
|
||||
post /json/simple (JsonReq) returns (JsonResp)
|
||||
|
||||
@doc (
|
||||
description: "复杂的 json 请求体接口"
|
||||
)
|
||||
@handler jsonComplex
|
||||
post /json/complex (ComplexJsonReq) returns (ComplexJsonResp)
|
||||
}
|
||||
|
||||
39
tools/goctl/api/swagger/example/go-swagger-cn.sh
Normal file
39
tools/goctl/api/swagger/example/go-swagger-cn.sh
Normal file
@@ -0,0 +1,39 @@
|
||||
#!/bin/bash
|
||||
|
||||
# 1. 检查并安装 swagger
|
||||
if ! command -v swagger &> /dev/null; then
|
||||
echo "swagger 未安装，正在从 GitHub 安装..."
|
||||
# 这里使用 go-swagger 的安装方式
|
||||
go install github.com/go-swagger/go-swagger/cmd/swagger@latest
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "安装 swagger 失败"
|
||||
exit 1
|
||||
fi
|
||||
echo "swagger 安装成功"
|
||||
else
|
||||
echo "swagger 已安装"
|
||||
fi
|
||||
|
||||
mkdir bin output
|
||||
|
||||
export GOBIN=$(pwd)/bin
|
||||
|
||||
# 2. 安装最新版 goctl
|
||||
go install ../../..
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "安装 goctl 失败"
|
||||
exit 1
|
||||
fi
|
||||
echo "goctl 安装成功"
|
||||
|
||||
# 3. 生成 swagger 文件
|
||||
echo "正在生成 swagger 文件..."
|
||||
./bin/goctl api swagger --api example_cn.api --dir output
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "生成 swagger 文件失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 4. 启动 swagger 服务
|
||||
echo "启动 swagger 服务..."
|
||||
swagger serve ./output/example_cn.json
|
||||
BIN
tools/goctl/api/swagger/example/go-swagger-ui-cn.png
Normal file
BIN
tools/goctl/api/swagger/example/go-swagger-ui-cn.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.3 MiB |
BIN
tools/goctl/api/swagger/example/go-swagger-ui.png
Normal file
BIN
tools/goctl/api/swagger/example/go-swagger-ui.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 3.6 MiB |
39
tools/goctl/api/swagger/example/go-swagger.sh
Normal file
39
tools/goctl/api/swagger/example/go-swagger.sh
Normal file
@@ -0,0 +1,39 @@
|
||||
#!/bin/bash
|
||||
|
||||
# 1. Check and install swagger if not exists
|
||||
if ! command -v swagger &> /dev/null; then
|
||||
echo "swagger not found, installing from GitHub..."
|
||||
# Using go-swagger installation method
|
||||
go install github.com/go-swagger/go-swagger/cmd/swagger@latest
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Failed to install swagger"
|
||||
exit 1
|
||||
fi
|
||||
echo "swagger installed successfully"
|
||||
else
|
||||
echo "swagger already installed"
|
||||
fi
|
||||
|
||||
mkdir bin output
|
||||
|
||||
export GOBIN=$(pwd)/bin
|
||||
|
||||
# 2. Install latest goctl version
|
||||
go install ../../..
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Failed to install goctl"
|
||||
exit 1
|
||||
fi
|
||||
echo "goctl installed successfully"
|
||||
|
||||
# 3. Generate swagger files
|
||||
echo "Generating swagger files..."
|
||||
./bin/goctl api swagger --api example.api --dir output
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Failed to generate swagger files"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 4. Start swagger server
|
||||
echo "Starting swagger server..."
|
||||
swagger serve ./output/example.json
|
||||
BIN
tools/goctl/api/swagger/example/swagger-ui-cn-example.png
Normal file
BIN
tools/goctl/api/swagger/example/swagger-ui-cn-example.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.7 MiB |
BIN
tools/goctl/api/swagger/example/swagger-ui-cn-model.png
Normal file
BIN
tools/goctl/api/swagger/example/swagger-ui-cn-model.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.4 MiB |
91
tools/goctl/api/swagger/example/swagger-ui-cn.sh
Normal file
91
tools/goctl/api/swagger/example/swagger-ui-cn.sh
Normal file
@@ -0,0 +1,91 @@
|
||||
#!/bin/bash
|
||||
|
||||
# 检查Docker是否运行的函数
|
||||
is_docker_running() {
|
||||
if ! docker info >/dev/null 2>&1; then
|
||||
return 1 # Docker未运行
|
||||
else
|
||||
return 0 # Docker正在运行
|
||||
fi
|
||||
}
|
||||
|
||||
mkdir bin output
|
||||
|
||||
export GOBIN=$(pwd)/bin
|
||||
|
||||
# 1. 检查并安装Docker（如果不存在）
|
||||
if ! command -v docker &> /dev/null; then
|
||||
echo "未检测到Docker，正在尝试安装..."
|
||||
|
||||
# 使用官方脚本安装Docker
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
rm get-docker.sh
|
||||
|
||||
# 验证安装
|
||||
if ! command -v docker &> /dev/null; then
|
||||
echo "Docker安装失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 将当前用户加入docker组（可能需要重新登录）
|
||||
sudo usermod -aG docker $USER
|
||||
echo "Docker安装成功。您可能需要注销并重新登录使更改生效。"
|
||||
else
|
||||
echo "Docker已安装"
|
||||
fi
|
||||
|
||||
# 2. 安装最新版goctl
|
||||
go install ../../..
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "goctl安装失败"
|
||||
exit 1
|
||||
fi
|
||||
echo "goctl 安装成功"
|
||||
|
||||
# 3. 生成swagger文件
|
||||
echo "正在生成swagger文件..."
|
||||
./bin/goctl api swagger --api example_cn.api --dir output
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "swagger文件生成失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 检查Docker是否运行
|
||||
if ! is_docker_running; then
|
||||
echo "Docker未运行，请先启动Docker服务"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 4. 清理现有的swagger-ui容器
|
||||
echo "正在清理现有的swagger-ui容器..."
|
||||
docker rm -f swagger-ui 2>/dev/null && echo "已移除现有的swagger-ui容器"
|
||||
|
||||
# 5. 在Docker中运行swagger-ui
|
||||
echo "正在启动swagger-ui容器..."
|
||||
docker run -d --name swagger-ui -p 8080:8080 \
|
||||
-e SWAGGER_JSON=/tmp/example.json \
|
||||
-v $(pwd)/output/example_cn.json:/tmp/example.json \
|
||||
swaggerapi/swagger-ui
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "swagger-ui容器启动失败"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 等待1秒确保服务就绪
|
||||
echo "等待swagger-ui初始化..."
|
||||
sleep 1
|
||||
|
||||
# 显示访问信息并尝试打开浏览器
|
||||
SWAGGER_URL="http://localhost:8080"
|
||||
echo -e "\nSwagger UI 已准备就绪，访问地址: \033[1;34m${SWAGGER_URL}\033[0m"
|
||||
echo "正在尝试在默认浏览器中打开..."
|
||||
|
||||
# 跨平台打开浏览器
|
||||
case "$(uname -s)" in
|
||||
Linux*) xdg-open "$SWAGGER_URL";;
|
||||
Darwin*) open "$SWAGGER_URL";;
|
||||
CYGWIN*|MINGW*|MSYS*) start "$SWAGGER_URL";;
|
||||
*) echo "无法在当前操作系统自动打开浏览器";;
|
||||
esac
|
||||
BIN
tools/goctl/api/swagger/example/swagger-ui-example.png
Normal file
BIN
tools/goctl/api/swagger/example/swagger-ui-example.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.6 MiB |
BIN
tools/goctl/api/swagger/example/swagger-ui-model.png
Normal file
BIN
tools/goctl/api/swagger/example/swagger-ui-model.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 2.4 MiB |
80
tools/goctl/api/swagger/example/swagger-ui.sh
Normal file
80
tools/goctl/api/swagger/example/swagger-ui.sh
Normal file
@@ -0,0 +1,80 @@
|
||||
#!/bin/bash
|
||||
|
||||
is_docker_running() {
|
||||
if ! docker info >/dev/null 2>&1; then
|
||||
return 1 # Docker is not running
|
||||
else
|
||||
return 0 # Docker is running
|
||||
fi
|
||||
}
|
||||
|
||||
mkdir bin output
|
||||
|
||||
export GOBIN=$(pwd)/bin
|
||||
|
||||
# 1. Check and install Docker if not exists
|
||||
if ! command -v docker &> /dev/null; then
|
||||
echo "Docker not found, attempting to install..."
|
||||
|
||||
# Install Docker using official installation script
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
rm get-docker.sh
|
||||
|
||||
# Verify installation
|
||||
if ! command -v docker &> /dev/null; then
|
||||
echo "Failed to install Docker"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Add current user to docker group (may require logout/login)
|
||||
sudo usermod -aG docker $USER
|
||||
echo "Docker installed successfully. You may need to logout and login again for changes to take effect."
|
||||
else
|
||||
echo "Docker already installed"
|
||||
fi
|
||||
|
||||
# 2. Install latest goctl version
|
||||
go install ../../..
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Failed to install goctl"
|
||||
exit 1
|
||||
fi
|
||||
echo "goctl installed successfully"
|
||||
|
||||
# 3. Generate swagger files
|
||||
echo "Generating swagger files..."
|
||||
./bin/goctl api swagger --api example.api --dir output
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Failed to generate swagger files"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! is_docker_running; then
|
||||
echo "Docker is not running, Pls start Docker first"
|
||||
fi
|
||||
|
||||
# 4. Clean up any existing swagger-ui container
|
||||
echo "Cleaning up existing swagger-ui containers..."
|
||||
docker rm -f swagger-ui 2>/dev/null && echo "Removed existing swagger-ui container"
|
||||
|
||||
# 5. Run swagger-ui in Docker
|
||||
echo "Starting swagger-ui in Docker..."
|
||||
docker run -d --name swagger-ui -p 8080:8080 -e SWAGGER_JSON=/tmp/example.json -v $(pwd)/output/example.json:/tmp/example.json swaggerapi/swagger-ui
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Failed to start swagger-ui container"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Waiting for swagger-ui to initialize..."
|
||||
sleep 1
|
||||
SWAGGER_URL="http://localhost:8080"
|
||||
echo -e "\nSwagger UI is ready at: \033[1;34m${SWAGGER_URL}\033[0m"
|
||||
echo "Opening in default browser..."
|
||||
|
||||
case "$(uname -s)" in
|
||||
Linux*) xdg-open "$SWAGGER_URL";;
|
||||
Darwin*) open "$SWAGGER_URL";;
|
||||
CYGWIN*|MINGW*|MSYS*) start "$SWAGGER_URL";;
|
||||
*) echo "System not supported";;
|
||||
esac
|
||||
Reference in New Issue
Block a user