go-swagger-api应用

该项目包含Swagger 2.0的golang实现 (又名OpenAPI 2.0)。 它提供了与swagger规范一起工作的工具。

swagger 是RESTful API的简单而强大的实现。

github：https://github.com/go-swagger/go-swagger

文档：https://goswagger.io/go-swagger/

聊聊Swagger

拥有全球最大的API工具生态系统，几乎所有现代编程语言和部署环境中都支持Swagger。

使用支持Swagger的API，您可以获得交互式文档、生成客户端SDK和发现服务。

Swagger帮助Apigee，Getty Images，Intuit，LivingSocial，McKesson，Microsoft，Morningstar和PayPal等公司使用RESTful api构建最佳服务。现在在2.0版本中，Swagger比以往任何时候都更加易用。它是完全开源的软件。

特点

go-swagger为go社区带来了一整套功能齐全、高性能的API组件，可与Swagger API配合使用: 开发服务端、客户端和数据模型。

• 按照swagger规范生成服务端代码
• 按照swagger规范生成客户端代码
• 按照swagger规范 (alpha阶段) 生成CLI (命令行工具)
• 支持jsonschema和swagger提供的大多数功能，包括多态
• 从带注释的go代码生成swagger规范
• 使用swagger规范的其他工具
• 出色的自定义功能，具有自带的扩展和可自定义的模板

我们对代码生成的理念是：生成惯用的，快速的go代码，它与golint，go vet等兼容得很好。

安装

从源安装

按章支持命令，docker，源安装，这里只记录下我用源码安装的操作。

> go version
go version go1.23.1 windows/amd64

> go install github.com/go-swagger/go-swagger/cmd/swagger@latest
...
> swagger.exe version
version: v0.31.0

# 查看环境变量
> go env
# 找到 GOPATH
GOPATH=C:\Users\hxd\go
# 进入目录，可以看到 swagger.exe 可执行文件，已经安装到gopath了
# 后续这个二进制可执行文件可以拷贝到项目中使用，统一版本避免版本问题

swagger工具说明：

Usage:
  swagger [OPTIONS] <command>

Swagger tries to support you as best as possible when building APIs.

It aims to represent the contract of your API with a language agnostic description of your application in json or yaml.

Application Options:
  -q, --quiet                  silence logs
      --log-output=LOG-FILE    redirect logs to file

Help Options:
  -h, --help                   Show this help message

Available commands:
  diff      diff swagger documents
  expand    expand $ref fields in a swagger spec
  flatten   flattens a swagger document
  generate  generate go code
  init      initialize a spec document
  mixin     merge swagger documents
  serve     serve spec and docs
  validate  validate the swagger document
  version   print the version

具体怎么用可以参考官网。

生成服务端

参考：https://goswagger.io/go-swagger/generate/server/

# 生成描述文件
swagger.exe init spec

# 初始化go mod
go mod init mlss-cc-service

# git初始化
git init

如图，我新建了一个项目，按照这个目录来构建应用

把swagger.exe放到项目里，编写好swagger.yaml 执行swagger生成代码

.\pkg\restapi\swagger\swagger.exe generate server -m ../models -f .\pkg\restapi\swagger\swagger.yaml -t .\pkg\restapi

新建启动文件，启动：

D:\goworkspace\mlss-cc-service> cd .\cmd\mlss-cc-go\     
PS D:\goworkspace\mlss-cc-service\cmd\mlss-cc-go> ls


    目录: D:\goworkspace\mlss-cc-service\cmd\mlss-cc-go


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
-a----         2024/3/26     16:34           1356 main.go


PS D:\goworkspace\mlss-cc-service\cmd\mlss-cc-go> go run .\main.go
Serving open API swagger at http://127.0.0.1:56434

已经开源到仓库
https://gitee.com/deepter/mlss-cc-service

https://gitee.com/deepter/mlss-cc-a

服务端中间件

再生成的可修改文件中，例如

中，最后一个一个方法添加全局中间件：

// The middleware configuration happens before anything, this middleware also applies to serving the swagger.json document.
// So this is a good place to plug in a panic handling middleware, logging and metrics.
func setupGlobalMiddleware(handler http.Handler) http.Handler {

	locateHandler := mv.NewLocateMiddleWare(handler)

	loginHandler := mv.NewLoginMiddleWare(locateHandler)

	return loginHandler
}

func NewLocateMiddleWare(handler http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		acceptLang := r.Header.Get("Accept-Language")
		logger.Logger().Debugf("acceptLanguate: %v", acceptLang)
		ctx := context.WithValue(r.Context(), "lang", acceptLang)
		//继续下一个拦截器
		handler.ServeHTTP(w, r.WithContext(ctx))
	})
}

func NewLoginMiddleWare(handler http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

		handler.ServeHTTP(w, r.WithContext(context.Background()))
	})
}