Skip to content

Commit 7dbf778

Browse files
yumaojun03yumaojun03
committed
补充gin swagger api
1 parent b9ac6a0 commit 7dbf778

File tree

13 files changed

+379
-36
lines changed

13 files changed

+379
-36
lines changed

‎examples/http_gin/docs/docs.go‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// Package docs Code generated by swaggo/swag. DO NOT EDIT
2+
package docs
3+
4+
import "github.com/swaggo/swag"
5+
6+
const docTemplate = `{
7+
"schemes": {{ marshal .Schemes }},
8+
"swagger": "2.0",
9+
"info": {
10+
"description": "{{escape .Description}}",
11+
"title": "{{.Title}}",
12+
"termsOfService": "http://swagger.io/terms/",
13+
"contact": {
14+
"name": "API Support",
15+
"url": "http://www.swagger.io/support",
16+
"email": "[email protected]"
17+
},
18+
"license": {
19+
"name": "Apache 2.0",
20+
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
21+
},
22+
"version": "{{.Version}}"
23+
},
24+
"host": "{{.Host}}",
25+
"basePath": "{{.BasePath}}",
26+
"paths": {
27+
"/api/v1/tags/{id}": {
28+
"put": {
29+
"description": "修改文章标签",
30+
"produces": [
31+
"application/json"
32+
],
33+
"tags": [
34+
"文章管理"
35+
],
36+
"summary": "修改文章标签",
37+
"parameters": [
38+
{
39+
"type": "integer",
40+
"description": "ID",
41+
"name": "id",
42+
"in": "path",
43+
"required": true
44+
},
45+
{
46+
"type": "string",
47+
"description": "ID",
48+
"name": "name",
49+
"in": "query",
50+
"required": true
51+
},
52+
{
53+
"type": "integer",
54+
"description": "State",
55+
"name": "state",
56+
"in": "query"
57+
},
58+
{
59+
"type": "string",
60+
"description": "ModifiedBy",
61+
"name": "modified_by",
62+
"in": "query",
63+
"required": true
64+
}
65+
],
66+
"responses": {
67+
"200": {
68+
"description": "{\"code\":200,\"data\":{},\"msg\":\"ok\"}",
69+
"schema": {
70+
"type": "string"
71+
}
72+
}
73+
}
74+
}
75+
}
76+
},
77+
"securityDefinitions": {
78+
"BasicAuth": {
79+
"type": "basic"
80+
}
81+
},
82+
"externalDocs": {
83+
"description": "OpenAPI",
84+
"url": "https://swagger.io/resources/open-api/"
85+
}
86+
}`
87+
88+
// SwaggerInfo holds exported Swagger Info so clients can modify it
89+
var SwaggerInfo = &swag.Spec{
90+
Version: "1.0",
91+
Host: "localhost:8080",
92+
BasePath: "/api/v1",
93+
Schemes: []string{},
94+
Title: "Swagger Example API",
95+
Description: "This is a sample server celler server.",
96+
InfoInstanceName: "swagger",
97+
SwaggerTemplate: docTemplate,
98+
LeftDelim: "{{",
99+
RightDelim: "}}",
100+
}
101+
102+
func init() {
103+
swag.Register(SwaggerInfo.InstanceName(), SwaggerInfo)
104+
}

‎examples/http_gin/docs/swagger.json‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
{
2+
"swagger": "2.0",
3+
"info": {
4+
"description": "This is a sample server celler server.",
5+
"title": "Swagger Example API",
6+
"termsOfService": "http://swagger.io/terms/",
7+
"contact": {
8+
"name": "API Support",
9+
"url": "http://www.swagger.io/support",
10+
"email": "[email protected]"
11+
},
12+
"license": {
13+
"name": "Apache 2.0",
14+
"url": "http://www.apache.org/licenses/LICENSE-2.0.html"
15+
},
16+
"version": "1.0"
17+
},
18+
"host": "localhost:8080",
19+
"basePath": "/api/v1",
20+
"paths": {
21+
"/api/v1/tags/{id}": {
22+
"put": {
23+
"description": "修改文章标签",
24+
"produces": [
25+
"application/json"
26+
],
27+
"tags": [
28+
"文章管理"
29+
],
30+
"summary": "修改文章标签",
31+
"parameters": [
32+
{
33+
"type": "integer",
34+
"description": "ID",
35+
"name": "id",
36+
"in": "path",
37+
"required": true
38+
},
39+
{
40+
"type": "string",
41+
"description": "ID",
42+
"name": "name",
43+
"in": "query",
44+
"required": true
45+
},
46+
{
47+
"type": "integer",
48+
"description": "State",
49+
"name": "state",
50+
"in": "query"
51+
},
52+
{
53+
"type": "string",
54+
"description": "ModifiedBy",
55+
"name": "modified_by",
56+
"in": "query",
57+
"required": true
58+
}
59+
],
60+
"responses": {
61+
"200": {
62+
"description": "{\"code\":200,\"data\":{},\"msg\":\"ok\"}",
63+
"schema": {
64+
"type": "string"
65+
}
66+
}
67+
}
68+
}
69+
}
70+
},
71+
"securityDefinitions": {
72+
"BasicAuth": {
73+
"type": "basic"
74+
}
75+
},
76+
"externalDocs": {
77+
"description": "OpenAPI",
78+
"url": "https://swagger.io/resources/open-api/"
79+
}
80+
}

‎examples/http_gin/docs/swagger.yaml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
basePath: /api/v1
2+
externalDocs:
3+
description: OpenAPI
4+
url: https://swagger.io/resources/open-api/
5+
host: localhost:8080
6+
info:
7+
contact:
8+
email: [email protected]
9+
name: API Support
10+
url: http://www.swagger.io/support
11+
description: This is a sample server celler server.
12+
license:
13+
name: Apache 2.0
14+
url: http://www.apache.org/licenses/LICENSE-2.0.html
15+
termsOfService: http://swagger.io/terms/
16+
title: Swagger Example API
17+
version: "1.0"
18+
paths:
19+
/api/v1/tags/{id}:
20+
put:
21+
description: 修改文章标签
22+
parameters:
23+
- description: ID
24+
in: path
25+
name: id
26+
required: true
27+
type: integer
28+
- description: ID
29+
in: query
30+
name: name
31+
required: true
32+
type: string
33+
- description: State
34+
in: query
35+
name: state
36+
type: integer
37+
- description: ModifiedBy
38+
in: query
39+
name: modified_by
40+
required: true
41+
type: string
42+
produces:
43+
- application/json
44+
responses:
45+
"200":
46+
description: '{"code":200,"data":{},"msg":"ok"}'
47+
schema:
48+
type: string
49+
summary: 修改文章标签
50+
tags:
51+
- 文章管理
52+
securityDefinitions:
53+
BasicAuth:
54+
type: basic
55+
swagger: "2.0"

‎examples/http_gin/main.go‎

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,12 +8,38 @@ import (
88
"github.com/infraboard/mcube/v2/ioc"
99
"github.com/infraboard/mcube/v2/ioc/server"
1010

11-
// 非业务模块
11+
// 引入生成好的API Doc代码
12+
_ "github.com/infraboard/mcube/v2/examples/http_gin/docs"
13+
// 引入集成工程
14+
_ "github.com/infraboard/mcube/v2/ioc/apps/apidoc/swaggo"
15+
16+
// 开启Health健康检查
1217
_ "github.com/infraboard/mcube/v2/ioc/apps/health/gin"
18+
// 开启Metric
1319
_ "github.com/infraboard/mcube/v2/ioc/apps/metric/gin"
20+
// 开启CORS, 允许资源跨域共享
1421
_ "github.com/infraboard/mcube/v2/ioc/config/cors"
1522
)
1623

24+
// @title Swagger Example API
25+
// @version 1.0
26+
// @description This is a sample server celler server.
27+
// @termsOfService http://swagger.io/terms/
28+
29+
// @contact.name API Support
30+
// @contact.url http://www.swagger.io/support
31+
// @contact.email [email protected]
32+
33+
// @license.name Apache 2.0
34+
// @license.url http://www.apache.org/licenses/LICENSE-2.0.html
35+
36+
// @host localhost:8080
37+
// @BasePath /api/v1
38+
39+
// @securityDefinitions.basic BasicAuth
40+
41+
// @externalDocs.description OpenAPI
42+
// @externalDocs.url https://swagger.io/resources/open-api/
1743
func main() {
1844
// 注册HTTP接口类
1945
ioc.Api().Registry(&HelloServiceApiHandler{})
@@ -42,9 +68,21 @@ func (h *HelloServiceApiHandler) Version() string {
4268

4369
// API路由
4470
func (h *HelloServiceApiHandler) Registry(r gin.IRouter) {
45-
r.GET("/", func(c *gin.Context) {
46-
c.JSON(http.StatusOK, gin.H{
47-
"data": "hello mcube",
48-
})
71+
r.GET("/", h.Hello)
72+
}
73+
74+
// @Summary 修改文章标签
75+
// @Description 修改文章标签
76+
// @Tags 文章管理
77+
// @Produce json
78+
// @Param id path int true "ID"
79+
// @Param name query string true "ID"
80+
// @Param state query int false "State"
81+
// @Param modified_by query string true "ModifiedBy"
82+
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
83+
// @Router /api/v1/tags/{id} [put]
84+
func (h *HelloServiceApiHandler) Hello(c *gin.Context) {
85+
c.JSON(http.StatusOK, gin.H{
86+
"data": "hello mcube",
4987
})
5088
}

‎go.mod‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ require (
2828
github.com/segmentio/kafka-go v0.4.44
2929
github.com/spf13/cobra v1.7.0
3030
github.com/stretchr/testify v1.8.4
31+
github.com/swaggo/swag v1.16.2
3132
github.com/ugorji/go/codec v1.2.11
3233
github.com/uptrace/opentelemetry-go-extra/otelgorm v0.2.3
3334
go.mongodb.org/mongo-driver v1.12.1
@@ -53,6 +54,7 @@ require (
5354
)
5455

5556
require (
57+
github.com/KyleBanks/depth v1.2.1 // indirect
5658
github.com/beorn7/perks v1.0.1 // indirect
5759
github.com/bytedance/sonic v1.10.1 // indirect
5860
github.com/cespare/xxhash/v2 v2.2.0 // indirect
@@ -110,6 +112,7 @@ require (
110112
golang.org/x/sys v0.15.0 // indirect
111113
golang.org/x/term v0.14.0 // indirect
112114
golang.org/x/text v0.14.0 // indirect
115+
golang.org/x/tools v0.7.0 // indirect
113116
google.golang.org/genproto/googleapis/rpc v0.0.0-20231002182017-d307bd883b97 // indirect
114117
gopkg.in/yaml.v2 v2.4.0 // indirect
115118
)

‎go.sum‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ github.com/AlecAivazis/survey/v2 v2.3.7 h1:6I/u8FvytdGsgonrYsVn2t8t4QiRnh6QSTqkk
44
github.com/AlecAivazis/survey/v2 v2.3.7/go.mod h1:xUTIdE4KCOIjsBAE1JYsUPoCqYdZ1reCfTwbto0Fduo=
55
github.com/BurntSushi/toml v1.3.2 h1:o7IhLm0Msx3BaB+n3Ag7L8EVlByGnpq14C4YWiu/gL8=
66
github.com/BurntSushi/toml v1.3.2/go.mod h1:CxXYINrC8qIiEnFrOxCa7Jy5BFHlXnUU2pbicEuybxQ=
7+
github.com/KyleBanks/depth v1.2.1 h1:5h8fQADFrWtarTdtDudMmGsC7GPbOAu6RVB3ffsVFHc=
8+
github.com/KyleBanks/depth v1.2.1/go.mod h1:jzSb9d0L43HxTQfT+oSA1EEp2q+ne2uh6XgeJcm8brE=
79
github.com/Netflix/go-expect v0.0.0-20220104043353-73e0943537d2 h1:+vx7roKuyA63nhn5WAunQHLTznkw5W8b1Xc0dNjp83s=
810
github.com/Netflix/go-expect v0.0.0-20220104043353-73e0943537d2/go.mod h1:HBCaDeC1lPdgDeDbhX8XFpy1jqjK0IBG8W5K+xYqA0w=
911
github.com/PuerkitoBio/purell v1.1.1/go.mod h1:c11w/QuzBsJSee3cPx9rAFu61PvFxuPbtSwDGJws/X0=
@@ -205,6 +207,8 @@ github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o
205207
github.com/stretchr/testify v1.8.2/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
206208
github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
207209
github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
210+
github.com/swaggo/swag v1.16.2 h1:28Pp+8DkQoV+HLzLx8RGJZXNGKbFqnuvSbAAtoxiY04=
211+
github.com/swaggo/swag v1.16.2/go.mod h1:6YzXnDcpr0767iOejs318CwYkCQqyGer6BizOg03f+E=
208212
github.com/twitchyliquid64/golang-asm v0.15.1 h1:SU5vSMR7hnwNxj24w34ZyCi/FmDZTkS4MhqMhdFk5YI=
209213
github.com/twitchyliquid64/golang-asm v0.15.1/go.mod h1:a1lVb/DtPvCB8fslRZhAngC2+aY1QWCk3Cedj/Gdt08=
210214
github.com/ugorji/go/codec v1.2.11 h1:BMaWp1Bb6fHwEtbplGBGJ498wD+LKlNSl25MjdZY4dU=
@@ -258,6 +262,7 @@ golang.org/x/crypto v0.15.0 h1:frVn1TEaCEaZcn3Tmd7Y2b5KKPaZ+I32Q2OA3kYp5TA=
258262
golang.org/x/crypto v0.15.0/go.mod h1:4ChreQoLWfG3xLDer1WdlH5NdlQ3+mwnQq1YTKY+72g=
259263
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
260264
golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
265+
golang.org/x/mod v0.9.0 h1:KENHtAZL2y3NLMYZeHY9DW8HW8V+kQyJsY/V9JlKvCs=
261266
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
262267
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
263268
golang.org/x/net v0.0.0-20210421230115-4e50805a0758/go.mod h1:72T/g9IO56b78aLF+1Kcs5dz7/ng1VjMUvfKvpfy+jM=
@@ -312,6 +317,8 @@ golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGm
312317
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
313318
golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
314319
golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
320+
golang.org/x/tools v0.7.0 h1:W4OVu8VVOaIO0yzWMNdepAulS7YfoS3Zabrm8DOXXU4=
321+
golang.org/x/tools v0.7.0/go.mod h1:4pg6aUX35JBAogB10C9AtvVL+qowtN4pT3CGSQex14s=
315322
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
316323
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
317324
google.golang.org/appengine v1.6.8 h1:IhEN5q69dyKagZPYMSdIjS2HqprW324FRQZJcGqPAsM=

0 commit comments

Comments
 (0)