Merge pull request #234 from yoyofx/dev

yoyofx · Feb 7, 2024 · 6924b33 · 6924b33
2 parents b06cc29 + 9a7eaec
commit 6924b33
Show file tree

Hide file tree

Showing 26 changed files with 877 additions and 341 deletions.
diff --git a/README.md b/README.md
@@ -34,7 +34,7 @@ QQ交流群： [780385870](https://qm.qq.com/cgi-bin/qm/qr?k=xP5ZSGZaLLgJIjK0P89
 go get github.com/yoyofx/yoyogo
 ```
 # 安装依赖 (由于某些原因国内下载不了依赖)
-##  go version < 1.13
+##  go version < 1.20
 ```bash
 window 下在 cmd 中执行：
 set GO111MODULE=on
@@ -122,6 +122,7 @@ github.com/shima-park/agollo
 * [x] RouteData路由数据 (/api/:version/) 与 Binding的集成 
 * [x] 路由组功能
 * [x] MVC默认模板功能
+* [X] MVC 自定义路由
 * [x] 路由过滤器 Filter
 
 ## MVC
@@ -139,7 +140,7 @@ github.com/shima-park/agollo
 * [X] 配置
 * [X] WebSocket
 * [X] JWT 
-* [ ] swagger
+* [X] swagger
 * [X] GRpc	 
 * [X] Prometheus 
 
@@ -194,6 +195,26 @@ func registerEndpoints(rb router.IRouterBuilder) {
 	Endpoints.UsePrometheus(rb)
 	Endpoints.UsePprof(rb)
 	Endpoints.UseJwt(rb)
+
+	//swagger api document
+	endpoints.UseSwaggerDoc(rb,
+		swagger.Info{
+			Title:          "YoyoGO 框架文档演示",
+			Version:        "v1.0.0",
+			Description:    "框架文档演示swagger文档 v1.0 [ #yoyogo](https://github.com/yoyofx/yoyogo).",
+			TermsOfService: "https://dev.yoyogo.run",
+			Contact: swagger.Contact{
+				Email: "zl.hxd@hotmail.com",
+				Name:  "yoyogo",
+			},
+			License: swagger.License{
+				Name: "MIT",
+				Url:  "https://opensource.org/licenses/MIT",
+			},
+		},
+		func(openapi *swagger.OpenApi) {
+			openapi.AddSecurityBearerAuth()
+		})
 
 	rb.GET("/error", func(ctx *context.HttpContext) {
 		panic("http get error")
@@ -250,11 +271,12 @@ func NewUserController(userAction models.IUserAction) *UserController {
 	return &UserController{userAction: userAction}
 }
 
-// 请求对象的参数化绑定
-type RegiserRequest struct {
-	mvc.RequestBody
-	UserName string `param:"username"`
-	Password string `param:"password"`
+// 请求对象的参数化绑定 , 使用 doc属性标注 支持swagger文档
+type RegisterRequest struct {
+	mvc.RequestBody `route:"/api/users/register" doc:"用户注册"`
+	UserName   string `uri:"userName" doc:"用户名"`
+	Password   string `uri:"password" doc:"密码"`
+	TestNumber uint64 `uri:"num" doc:"数字"`
 }
 
 // Register函数自动绑定参数
@@ -268,6 +290,26 @@ func (this *UserController) GetInfo() mvc.ApiResult {
 	return this.OK(this.userAction.Login("zhang"))
 }
 
+// DocumentResponse custom document response , use doc tag for swagger
+type DocumentResponse struct {
+	Message string        `json:"message" doc:"消息"`
+	List    []DocumentDto `json:"list" doc:"文档列表"`
+	Success bool          `json:"success" doc:"是否成功"`
+}
+
+// Swagger API 文档支持
+func (controller UserController) GetDocumentList(request *struct {
+	mvc.RequestGET `route:"/v1/user/doc/list" doc:"获取全部文档列表"`
+}) DocumentResponse {
+
+	return DocumentResponse{Message: "GetDocumentList", List: []DocumentDto{
+		{Id: 1, Name: "test1", Time: time.Now()}, {Id: 2, Name: "test2", Time: time.Now()},
+		{Id: 3, Name: "test3", Time: time.Now()}, {Id: 4, Name: "test4", Time: time.Now()},
+		{Id: 5, Name: "test5", Time: time.Now()}, {Id: 6, Name: "test6", Time: time.Now()},
+	}, Success: true}
+}
+
+
 // Web程序的开始与停止事件
 func fireApplicationLifeEvent(life *abstractions.ApplicationLife) {
 	printDataEvent := func(event abstractions.ApplicationEvent) {

diff --git a/README_En.md b/README_En.md
@@ -93,8 +93,8 @@ func main() {
 * [X] configtion
 * [X] WebSocket
 * [X] JWT 
-* [ ] swagger
-* [ ] GRpc
+* [X] swagger
+* [X] GRpc
 * [X] Prometheus 
 
 

diff --git a/examples/grpc-demo/go.mod b/examples/grpc-demo/go.mod
@@ -45,7 +45,7 @@ require (
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	go.uber.org/zap v1.21.0 // indirect
-	golang.org/x/crypto v0.16.0 // indirect
+	golang.org/x/crypto v0.17.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
 	golang.org/x/net v0.19.0 // indirect
 	golang.org/x/sync v0.5.0 // indirect

diff --git a/examples/simpleweb/contollers/dbcontroller.go b/examples/simpleweb/contollers/dbcontroller.go
@@ -12,8 +12,8 @@ import (
 )
 
 type DbController struct {
-	mvc.ApiController
-	dbConfig configuration.OptionsSnapshot[models.MyConfig]
+	mvc.ApiController `doc:"数据库接口Controller"`
+	dbConfig          configuration.OptionsSnapshot[models.MyConfig]
 }
 
 func NewDbController(snapshotOptions configuration.OptionsSnapshot[models.MyConfig]) *DbController {

diff --git a/examples/simpleweb/contollers/hubcontroller.go b/examples/simpleweb/contollers/hubcontroller.go
@@ -13,7 +13,7 @@ import (
 
 // websocket hub
 type HubController struct {
-	mvc.ApiController
+	mvc.ApiController `doc:"websocket hub controller"`
 
 	hub         *hubs.Hub
 	redisClient *redisdb.RedisDataSource

diff --git a/examples/simpleweb/contollers/sdcontroller.go b/examples/simpleweb/contollers/sdcontroller.go
@@ -8,7 +8,7 @@ import (
 )
 
 type SDController struct {
-	mvc.ApiController
+	mvc.ApiController `doc:"服务发现接口Controller"`
 	discoveryCache    servicediscovery.Cache
 	discoveryClient   servicediscovery.IServiceDiscoveryClient
 	discoverySelector servicediscovery.ISelector

diff --git a/examples/simpleweb/contollers/usercontroller.go b/examples/simpleweb/contollers/usercontroller.go
@@ -11,10 +11,11 @@ import (
 	"github.com/yoyofx/yoyogo/web/mvc"
 	"mime/multipart"
 	"simpleweb/models"
+	"time"
 )
 
 type UserController struct {
-	mvc.ApiController `route:"user"`
+	mvc.ApiController `route:"user" doc:"用户接口Controller"`
 
 	userAction      models.IUserAction
 	discoveryClient servicediscovery.IServiceDiscovery
@@ -26,11 +27,11 @@ func NewUserController(userAction models.IUserAction, sd servicediscovery.IServi
 }
 
 type RegisterRequest struct {
-	mvc.RequestBody `route:"/v1/users/register"`
+	mvc.RequestBody `route:"/api/users/register" doc:"用户注册"`
 
-	UserName   string `uri:"userName"`
-	Password   string `uri:"password"`
-	TestNumber uint64 `uri:"num"`
+	UserName   string `uri:"userName" doc:"用户名"`
+	Password   string `uri:"password" doc:"密码"`
+	TestNumber uint64 `uri:"num" doc:"数字"`
 }
 
 func (controller UserController) Register(ctx *context.HttpContext, request *RegisterRequest) mvc.ApiResult {
@@ -41,11 +42,10 @@ func (controller UserController) Register(ctx *context.HttpContext, request *Reg
 }
 
 type PostUserInfoRequest struct {
-	mvc.RequestBody //`route:"/{id}"`
-
-	UserName string `form:"userName" json:"userName"`
-	Password string `form:"password" json:"password"`
-	Token    string `header:"Authorization" json:"token"`
+	mvc.RequestBody `doc:"用户信息提交"` //`route:"/{id}"`
+	UserName        string         `form:"userName" json:"userName" doc:"用户名"`
+	Password        string         `form:"password" json:"password" doc:"密码"`
+	Token           string         `header:"Authorization" json:"token" doc:"token"`
 }
 
 func (controller UserController) PostUserInfo(ctx *context.HttpContext, request *PostUserInfoRequest) actionresult.IActionResult {
@@ -99,13 +99,13 @@ func (controller UserController) GetTestApiResult() mvc.ApiResult {
 }
 
 type UserInfo struct {
-	UserName string                `form:"user" json:"user" binding:"required"`
-	Number   int                   `form:"num" json:"num" binding:"gt=0,lt=10"`
-	Id       string                `form:"id" json:"id" binding:"required,gt=0,lt=10"`
-	Image    *multipart.FileHeader `form:"file"`
+	UserName string                `form:"user" json:"user" binding:"required" doc:"用户名"`
+	Number   int                   `form:"num" json:"num" binding:"gt=0,lt=10" doc:"数字"`
+	Id       string                `form:"id" json:"id" binding:"required,gt=0,lt=10" doc:"id"`
+	Image    *multipart.FileHeader `form:"file" doc:"图片文件"`
 }
 
-//FromBody
+// FromBody
 func (controller UserController) DefaultBinding(ctx *context.HttpContext) mvc.ApiResult {
 	userInfo := &UserInfo{}
 	err := ctx.Bind(userInfo)
@@ -115,7 +115,7 @@ func (controller UserController) DefaultBinding(ctx *context.HttpContext) mvc.Ap
 	return controller.OK(userInfo)
 }
 
-//FromBody
+// FromBody
 func (controller UserController) JsonBinding(ctx *context.HttpContext) mvc.ApiResult {
 	userInfo := &UserInfo{}
 	err := ctx.BindWith(userInfo, binding.JSON)
@@ -125,7 +125,7 @@ func (controller UserController) JsonBinding(ctx *context.HttpContext) mvc.ApiRe
 	return controller.OK(userInfo)
 }
 
-//FromQuery
+// FromQuery
 func (controller UserController) GetQueryBinding(ctx *context.HttpContext) mvc.ApiResult {
 	fmt.Println("进入方法")
 	fmt.Println(controller.config.Get("env"))
@@ -140,9 +140,9 @@ func (controller UserController) GetQueryBinding(ctx *context.HttpContext) mvc.A
 }
 
 type UploadForm struct {
-	mvc.RequestBody
-	File *multipart.FileHeader `form:"file1"`
-	Key  string                `form:"key"`
+	mvc.RequestBody `doc:"文件上传"`
+	File            *multipart.FileHeader `form:"file1" doc:"文件"`
+	Key             string                `form:"key" doc:"文件ID"`
 }
 
 func (controller UserController) Upload(form *UploadForm) mvc.ApiResult {
@@ -154,11 +154,48 @@ func (controller UserController) Upload(form *UploadForm) mvc.ApiResult {
 
 }
 
+// TestFunc attribute routing @route("/v1/user/{id}/test")
 func (controller UserController) TestFunc(request *struct {
-	mvc.RequestGET `route:"/v1/user/:id/test"`
-	Name           string `uri:"name"`
-	Id             uint64 `path:"id"`
+	mvc.RequestGET `route:"/v1/user/:id/test" doc:"测试接口"`
+	Name           string `uri:"name" doc:"测试用户名"`
+	Id             uint64 `path:"id" doc:"测试ID"`
 }) mvc.ApiResult {
 
 	return mvc.Success(request)
 }
+
+type DocumentDto struct {
+	Id   uint64    `json:"id" doc:"文档ID"`
+	Name string    `json:"name" doc:"文档名称"`
+	Time time.Time `json:"time" doc:"创建时间"`
+}
+
+// GetDocumentById TestFunc attribute routing @route("/v1/user/doc/{id}")
+func (controller UserController) GetDocumentById(request *struct {
+	mvc.RequestGET `route:"/v1/user/doc/:id" doc:"根据ID获取文档"`
+	Id             uint64 `path:"id" doc:"文档ID"`
+}) mvc.ApiDocResult[DocumentDto] {
+
+	response := DocumentDto{Id: request.Id, Name: "test", Time: time.Now()}
+	return mvc.ApiDocumentResult[DocumentDto]().Success().
+		Data(response).
+		Message("GetDocumentById").Build()
+}
+
+// DocumentResponse custom document response
+type DocumentResponse struct {
+	Message string        `json:"message" doc:"消息"`
+	List    []DocumentDto `json:"list" doc:"文档列表"`
+	Success bool          `json:"success" doc:"是否成功"`
+}
+
+func (controller UserController) GetDocumentList(request *struct {
+	mvc.RequestGET `route:"/v1/user/doc/list" doc:"获取全部文档列表"`
+}) DocumentResponse {
+
+	return DocumentResponse{Message: "GetDocumentList", List: []DocumentDto{
+		{Id: 1, Name: "test1", Time: time.Now()}, {Id: 2, Name: "test2", Time: time.Now()},
+		{Id: 3, Name: "test3", Time: time.Now()}, {Id: 4, Name: "test4", Time: time.Now()},
+		{Id: 5, Name: "test5", Time: time.Now()}, {Id: 6, Name: "test6", Time: time.Now()},
+	}, Success: true}
+}
diff --git a/examples/simpleweb/go.mod b/examples/simpleweb/go.mod
@@ -70,7 +70,7 @@ require (
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
 	go.uber.org/zap v1.21.0 // indirect
-	golang.org/x/crypto v0.16.0 // indirect
+	golang.org/x/crypto v0.17.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
 	golang.org/x/image v0.14.0 // indirect
 	golang.org/x/net v0.19.0 // indirect

diff --git a/examples/simpleweb/main.go b/examples/simpleweb/main.go
@@ -9,6 +9,7 @@ import (
 	_ "github.com/yoyofx/yoyogo/pkg/datasources/mysql"
 	_ "github.com/yoyofx/yoyogo/pkg/datasources/redis"
 	"github.com/yoyofx/yoyogo/pkg/servicediscovery/nacos"
+	"github.com/yoyofx/yoyogo/pkg/swagger"
 	"github.com/yoyofx/yoyogo/web"
 	"github.com/yoyofx/yoyogo/web/context"
 	"github.com/yoyofx/yoyogo/web/endpoints"
@@ -42,7 +43,7 @@ func main() {
 	webHost.Run()
 }
 
-//CreateCustomBuilder Create the builder of Web host
+// CreateCustomBuilder Create the builder of Web host
 func CreateCustomBuilder() *abstractions.HostBuilder {
 	//config := nacosconfig.RemoteConfig("config")
 	//config := apollo.RemoteConfig("config")
@@ -94,7 +95,7 @@ func CreateCustomBuilder() *abstractions.HostBuilder {
 
 //*/
 
-//region router config function
+// region router config function
 func registerEndpointRouterConfig(rb router.IRouterBuilder) {
 	endpoints.UseHealth(rb)
 	endpoints.UseViz(rb)
@@ -104,6 +105,24 @@ func registerEndpointRouterConfig(rb router.IRouterBuilder) {
 	endpoints.UseLiveness(rb)
 	endpoints.UseJwt(rb)
 	endpoints.UseRouteInfo(rb)
+	endpoints.UseSwaggerDoc(rb,
+		swagger.Info{
+			Title:          "YoyoGO 框架文档演示",
+			Version:        "v1.0.0",
+			Description:    "框架文档演示swagger文档 v1.0 [ #yoyogo](https://github.com/yoyofx/yoyogo).",
+			TermsOfService: "https://dev.yoyogo.run",
+			Contact: swagger.Contact{
+				Email: "zl.hxd@hotmail.com",
+				Name:  "yoyogo",
+			},
+			License: swagger.License{
+				Name: "MIT",
+				Url:  "https://opensource.org/licenses/MIT",
+			},
+		},
+		func(openapi *swagger.OpenApi) {
+			openapi.AddSecurityBearerAuth()
+		})
 
 	rb.GET("/error", func(ctx *context.HttpContext) {
 		panic("http get error")
@@ -145,8 +164,8 @@ type UserInfo struct {
 	Id       string `param:"id"`
 }
 
-//HttpGet request: /info  or /v1/api/info
-//bind UserInfo for id,q1,username
+// HttpGet request: /info  or /v1/api/info
+// bind UserInfo for id,q1,username
 func GetInfo(ctx *context.HttpContext) {
 	ctx.JSON(200, context.H{"info": "ok"})
 }
@@ -160,8 +179,8 @@ func GetInfoByIOC(ctx *context.HttpContext) {
 	})
 }
 
-//bootstrap binding
-//HttpPost request: /info/:id ?q1=abc&username=123
+// bootstrap binding
+// HttpPost request: /info/:id ?q1=abc&username=123
 func PostInfo(ctx *context.HttpContext) {
 	qs_q1 := ctx.Input.Query("q1")
 	pd_name := ctx.Input.Param("username")

diff --git a/examples/xxl-job-console/go.mod b/examples/xxl-job-console/go.mod
@@ -32,7 +32,7 @@ require (
 	github.com/yoyofxteam/reflectx v0.2.3 // indirect
 	go.uber.org/atomic v1.9.0 // indirect
 	go.uber.org/multierr v1.9.0 // indirect
-	golang.org/x/crypto v0.16.0 // indirect
+	golang.org/x/crypto v0.17.0 // indirect
 	golang.org/x/exp v0.0.0-20230905200255-921286631fa9 // indirect
 	golang.org/x/sys v0.15.0 // indirect
 	golang.org/x/term v0.15.0 // indirect