一、基础环境安装及版本
说明: Golang版本为1.22.5
- 安装swag, 版本为: v1.16.3
[root@base /]# go install github.com/swaggo/swag/cmd/swag@latest
[root@base /]# swag -v
swag version v1.16.3
- 安装swag2op, 版本为: v1.0.0
[root@base /]# go install github.com/zxmfke/swagger2openapi3/cmd/swag2op@latest
[root@base /]# swag2op -v
swag2op version 1.0.0
- Gokit微服务相关第三方包版本(go mod)
- 集成nacos(后续章节介绍)
- 集成viper(后续章节介绍)
- 集成http-swagger v2.0.2版本
- 集成swag v1.16.3
- 集成zap(后续章节介绍)
go 1.22.5
require (
github.com/go-kit/kit v0.13.0
github.com/goharbor/go-client v0.210.0
github.com/gorilla/mux v1.8.1
github.com/liangboceo/nacos-viper-remote v1.0.1
github.com/nacos-group/nacos-sdk-go/v2 v2.2.7
github.com/spf13/viper v1.19.0
github.com/swaggo/http-swagger/v2 v2.0.2
github.com/swaggo/swag v1.16.3
go.uber.org/zap v1.27.0
gopkg.in/natefinch/lumberjack.v2 v2.2.1
)
二、工程基础目录
- 目录结构划分
[root@base /]# tree
/
├── ticc-cloud-smart-calculation
├── cache
├── config
├── docs # 本章节重点关注此文件夹
├── global
├── harbor
├── log
├── router
├── utils
├── .gitgnore
├── LICENSE
├── main.go
├── README.en.md
├── README.md
└── ticc-cloud-smart-calculation
- 部分api代码展示
- endpoint 部分代码展示, 编写swagger文档, 文档注释不在介绍, 代@符号交由swagger识别, 否则不识别
......
// MakeGetHarborProjectEndpoint
// @Title MakeGetHarborProjectEndpoint
// @Description 根据用户、密码、项目名称、项目ID获取Harbor项目信息
// @Tags harbor
// @Auth alittlexincan@163.com 时间（2024/07/22 11:36）
// @Router /harbor/project [get]
// @Accept application/json
// @Produce application/json
// @Param username query string true "用户名称" default(admin)
// @Param password query string true "密码" default(Troila@123)
// @Param projectName query string false "项目名称" default(library)
// @Param projectId query string false "项目id" default(1)
// @Success 200 {object} response.SuccessResult{data=vo.HarborProjectVo} "正常结果实例"
// @Failure 500 {object} response.ErrorResult "错误结果实例"
// Param harborProjectService service.HarborProjectService "镜像仓库项目接口"
func MakeGetHarborProjectEndpoint(harborProjectService service.HarborProjectService) endpoint.Endpoint {
return func(ctx context.Context, request interface{}) (response interface{}, err error) {
projectDto := request.(dto.HarborProjectDto)
project, err := harborProjectService.GetHarborProject(projectDto.Username, projectDto.Password, projectDto.ProjectName, projectDto.ProjectId)
if err != nil {
return result.Error(err, nil), nil
}
return result.Success(project), nil
}
}
......
三、 生成API文档
- 查看swag2op帮助文档
[root@base /]# swag2op -h
NAME:
swag2op init - Create docs.go
USAGE:
swag2op init [command options]
OPTIONS:
--disableOpenApiV3, --nc Convert generated swagger.json to openApi v3 format, enabled by default (default: false)
--disableOverwriteSwaggerV2, --disOverwrite Generate openApi 3.0 json do not overwrite origin swagger.json, disable by default (default: false)
--openapiOutputDir value, --openo value OpenapiOutputDir directory for generated OpenApi v3 spec, default is ./openapi
--quiet, -q Make the logger quiet. (default: false)
--generalInfo value, -g value Go file path in which 'swagger general API Info' is written (default: "main.go")
--dir value, -d value Directories you want to parse,comma separated and general-info file must be in the first one (default: "./")
--exclude value Exclude directories and files when searching, comma separated
--propertyStrategy value, -p value Property Naming Strategy like snakecase,camelcase,pascalcase (default: "camelcase")
--output value, -o value OutputDir directory for all the generated files(swagger.json, swagger.yaml and docs.go) (default: "./docs")
--outputTypes value, --ot value OutputDir types of generated files (docs.go, swagger.json, swagger.yaml) like go,json,yaml (default: "go,json,yaml")
--parseVendor Parse go files in 'vendor' folder, disabled by default (default: false)
--parseDependencyLevel value, --pdl value Parse go files inside dependency folder, 0 disabled, 1 only parse models, 2 only parse operations, 3 parse all (default: 0)
--parseDependency, --pd Parse go files inside dependency folder, disabled by default (default: false)
--markdownFiles value, --md value Parse folder containing markdown files to use as description, disabled by default
--codeExampleFiles value, --cef value Parse folder containing code example files to use for the x-codeSamples extension, disabled by default
--parseInternal Parse go files in internal packages, disabled by default (default: false)
--generatedTime Generate timestamp at the top of docs.go, disabled by default (default: false)
--parseDepth value Dependency parse depth (default: 100)
--requiredByDefault Set validation required for all fields by default (default: false)
--instanceName value This parameter can be used to name different swagger document instances. It is optional.
--overridesFile value File to read global type overrides from. (default: ".swaggo")
--parseGoList Parse dependency via 'go list' (default: true)
--parseExtension value Parse only those operations that match given extension
--tags value, -t value A comma-separated list of tags to filter the APIs for which the documentation is generated.Special case if the tag is prefixed with the '!' character then the APIs with that tag will be excluded
--templateDelims value, --td value Provide custom delimiters for Go template generation. The format is leftDelim,rightDelim. For example: "[[,]]"
--packageName --output A package name of docs.go, using output directory name by default (check --output option)
--collectionFormat value, --cf value Set default collection format (default: "csv")
--packagePrefix value Parse only packages whose import path match the given prefix, comma separated
--state value Set host state for swagger.json
--help, -h show help
- 部分参数解释
- --disableOpenApiV3, --nc 将生成的 swagger.json 转换为 OpenAPI v3 格式，默认情况下启用， (默认值：false)
- --disableOverwriteSwaggerV2, --disOverwrite 生成 OpenAPI 3.0 JSON，不覆盖原始的 swagger.json，默认情况下禁用（默认值：false）
- --output value, -o value 自定义文档存储文件夹, 默认是./docs, 此处改成 ./docs/v2
- --openapiOutputDir value, --openo V3文档生成后保存的目录是 ./openapi, 此处改成 ./docs/v3
- 主要用到这几个, 看倒数五行!看倒数五行!看倒数五行!
[root@base /]# swag2op init --nc=false --disOverwrite=true -o=./docs/v2 --openo=./docs/v3
2024/07/31 18:43:24 Generate swagger docs....
2024/07/31 18:43:24 Generate general API Info, search dir:./
2024/07/31 18:43:24 Generating response.SuccessResult
2024/07/31 18:43:24 Generating vo.HarborProjectVo
2024/07/31 18:43:24 Generating response.ErrorResult
2024/07/31 18:43:24 Generating vo.HarborProjectListVo
2024/07/31 18:43:24 Generating bo.HarborProjectBo
2024/07/31 18:43:24 Generating vo.HarborUserVo
2024/07/31 18:43:24 create docs.go at docs/v2/docs.go
2024/07/31 18:43:24 create swagger.json at docs/v2/swagger.json
2024/07/31 18:43:24 create swagger.yaml at docs/v2/swagger.yaml
2024/07/31 18:43:24 generate to docs/v3/swagger.json
2024/07/31 18:43:24 generate to docs/v3/swagger.yaml
- 生成后项目工程目录如下
[root@base /]# tree
/
├── ticc-cloud-smart-calculation
├── cache
├── config
├── docs # 本章节重点关注此文件夹
├── v2 # 生成v2目录
├── docs.go
├── swagger.json
├── swagger.yaml
├── v3 # 生成v3目录
├── swagger.json
├── swagger.yaml
├── global
├── harbor
├── log
├── router
├── utils
├── .gitgnore
├── LICENSE
├── main.go
├── README.en.md
├── README.md
└── ticc-cloud-smart-calculation
四、路由改造
- 使用github.com/swaggo/http-swagger/v2
- 强制引入ticc.troila.com/ticc-cloud-smart-calculation/docs/v2
- 将刚才生成的docs文件夹添加到静态路由
- 分别指定swagger index.html 根据不同版本路由访问不同版本的swagger.json文件, 同时也添加到路由中
- 关键代码如下
// 将文档库的文件路径添加到静态路由
router.PathPrefix("/docs/").Handler(http.StripPrefix("/docs/", http.FileServer(http.Dir("docs"))))
// api v2 版本文档路由
router.PathPrefix("/swagger/v2/").Handler(httpSwagger.Handler(httpSwagger.URL("/docs/v2/swagger.json"))).Methods(http.MethodGet)
// api v3 版本文档路由
router.PathPrefix("/swagger/v3/").Handler(httpSwagger.Handler(httpSwagger.URL("/docs/v3/swagger.json"))).Methods(http.MethodGet)
- 完整代码
// Title router.go
// Description 路由配置
// Author alittlexincan@163.com 2024/07/22 11:36
// update alittlexincan@163.com 2024/07/22 11:36
package router
import (
"github.com/gorilla/mux"
"github.com/swaggo/http-swagger/v2"
"net/http"
_ "ticc.troila.com/ticc-cloud-smart-calculation/docs/v2"
project "ticc.troila.com/ticc-cloud-smart-calculation/harbor/project/handler"
user "ticc.troila.com/ticc-cloud-smart-calculation/harbor/user/handler"
)
// Router
// Title Router
// Description 系统路由列表配置
// Auth alittlexincan@163.com "时间（2024/07/22 11:36）"
// Return *mux.Router "返回路由对象"
func Router() *mux.Router {
router := mux.NewRouter()
// 将文档库的文件路径添加到静态路由
router.PathPrefix("/docs/").Handler(http.StripPrefix("/docs/", http.FileServer(http.Dir("docs"))))
// api v2 版本文档路由
router.PathPrefix("/swagger/v2/").Handler(httpSwagger.Handler(httpSwagger.URL("/docs/v2/swagger.json"))).Methods(http.MethodGet)
// api v3 版本文档路由
router.PathPrefix("/swagger/v3/").Handler(httpSwagger.Handler(httpSwagger.URL("/docs/v3/swagger.json"))).Methods(http.MethodGet)
// Harbor项目路由列表
harbor := router.PathPrefix("/harbor").Subrouter()
harborProject := harbor.PathPrefix("/project").Subrouter()
harborProject.Methods(http.MethodGet).Subrouter().Handle("", project.GetHarborProjectHandler())
harborProject.Methods(http.MethodGet).Subrouter().Handle("/list", project.GetHarborProjectListHandler())
harborProject.Methods(http.MethodPost).Subrouter().Handle("/create", project.CreateHarborProjectHandler())
harborProject.Methods(http.MethodPost).Subrouter().Handle("/delete", project.DeleteHarborProjectHandler())
// Harbor 用户路由列表
harborUser := harbor.PathPrefix("/user").Subrouter()
harborUser.Methods(http.MethodGet).Subrouter().Handle("", user.SearchHarborUserHandler())
harborUser.Methods(http.MethodPost).Subrouter().Handle("/create", user.CreateHarborUserHandler())
harborUser.Methods(http.MethodPost).Subrouter().Handle("/delete", user.DeleteHarborUserHandler())
return router
}
五、主函数、程序入口改造
- main.go 强制引入_ "ticc.troila.com/ticc-cloud-smart-calculation/docs/v2", 指定doc.go
// Package main
// Title main.go
// Description 程序主入口
// Author alittlexincan@163.com 2024/07/22 11:36
// Update alittlexincan@163.com 2024/07/22 11:36
package main
import (
"github.com/spf13/viper"
"go.uber.org/zap"
"net/http"
_ "ticc.troila.com/ticc-cloud-smart-calculation/docs/v2"
"ticc.troila.com/ticc-cloud-smart-calculation/global"
"ticc.troila.com/ticc-cloud-smart-calculation/router"
)
// @Title 智算调度服务
// @version 0.0.1
// @Description 智算调度服务
// @termsOfService https://xincan.github.io
// @contact.name xincan
// @contact.url https://xincan.github.io
// @contact.email alittlexincan@163.com
// @BasePath /
// @Auth alittlexincan@163.com "时间（2024/07/22 11:36）"
func main() {
// 初始化配置文件
global.InitGlobal()
// 初始化日志
global.Logger.Info("服务启动成功", zap.String("port", viper.GetString("service.port")))
global.Logger.Info("swagger文档地址", zap.String("url", "http://localhost:"+viper.GetString("service.port")+"/swagger/index.html"))
_ = http.ListenAndServe(":"+viper.GetString("service.port"), router.Router())
}
六、启动服务, 炫一把
- 启动服务
GOROOT=/Users/xincan/software/go/go-1.22.5 #gosetup
GOPATH=/Users/xincan/workspace/goworkspace #gosetup
/Users/xincan/software/go/go-1.22.5/bin/go build -o /Users/xincan/Library/Caches/JetBrains/GoLand2023.3/tmp/GoLand/___go_build_ticc_troila_com_ticc_cloud_smart_calculation ticc.troila.com/ticc-cloud-smart-calculation #gosetup
/Users/xincan/Library/Caches/JetBrains/GoLand2023.3/tmp/GoLand/___go_build_ticc_troila_com_ticc_cloud_smart_calculation
{"level":"\u001b[34mINFO\u001b[0m","time":"2024-07-31T18:59:58.902+0800","caller":"config/viper.config.go:34","msg":"Viper插件初始化成功"}
{"level":"\u001b[34mINFO\u001b[0m","time":"2024-07-31T18:59:58.903+0800","caller":"config/viper.config.go:53","msg":"Viper插件读取远程配置数据"}
{"level":"\u001b[34mINFO\u001b[0m","time":"2024-07-31T18:59:59.028+0800","caller":"config/viper.config.go:81","msg":"Viper远程获取Nacos配置中心配置数据","service":{"log":{"compress":"false,","maxage":"7,","maxbackups":"10,","maxsize":"10,"},-cloud-smart-calculation","port":8030},"nacos":{"cachedir":"","client":{"group":"ticc","namespaceid":"ticc-dev"},"config":{"checked":"viper","dataid":"ticc-cloud-smart-calculation.yaml","group":"ticc","namespaceid":"ticc-dev"},"ip":"127.0.0.1","logdir":"./log/nacos","password":"nacos","port":8848,"timeoutms":5000,"username":"nacos"},"ticc":{"harbor":{"password":"Troila@123","url":"http://127.0.0.1:9000","username":"admin"},"test":{"age":1,"name":"wangwu"},"viper":"remote"}}
{"level":"\u001b[34mINFO\u001b[0m","time":"2024-07-31T18:59:59.261+0800","caller":"config/nacos.config.go:71","msg":"Nacos服务注册成功","success":true,"ip":"127.0.0.1","port":8848,"serviceName":"ticc-cloud-smart-calculation"}
{"level":"\u001b[34mINFO\u001b[0m","time":"2024-07-31T18:59:59.261+0800","caller":"ticc-cloud-smart-calculation/main.go:32","msg":"服务启动成功","port":"8030"}
{"level":"\u001b[34mINFO\u001b[0m","time":"2024-07-31T18:59:59.261+0800","caller":"ticc-cloud-smart-calculation/main.go:33","msg":"swagger文档地址","url":"http://127.0.0.1:8030/swagger/index.html"}
- 验证 swagger v2 版本API。访问 http://localhost:8030/swagger/v2/index.html
- 验证 swagger v2 版本API。访问 http://localhost:8030/docs/v2/swagger.json
- 验证 swagger v3 版本API。访问 http://localhost:8030/swagger/v3/index.html 出现OAS3
- 验证 swagger v3 版本API。http://localhost:8030/docs/v3/swagger.json
七、结尾
每天前进一小步, Java转Go的第1天的JAVA开发狗.
