go swagger怎么玩？（使用swagger为go项目生成python的SDK）

矫情吗；* 2023-07-01 03:27 18阅读 0赞

# 人生如梦  一樽还酹江月 #

**目录**

go方面需要做的准备

生成对应语言的SDK

生成后怎么调用验证

> 提示：生成哪种语言的SDK只是本文的其中一步，具体哪种语言可以选择，没有任何影响；
> 
> 源码已提交，代码地址：[https://gitlab.com/wanglan/gin-coms.git][https_gitlab.com_wanglan_gin-coms.git]，swagger分支（该项目是自己写的一个gin的小项目，试了下go mod模式和gin框架，写了简单的API，swagger分支就是专门实践swagger的）

## go方面需要做的准备 ##

1，下载go-swagger包(已为你准备好：[https://download.csdn.net/download/HYZX\_9987/12115864][https_download.csdn.net_download_HYZX_9987_12115864])，把文件放到你的$GOPATH\\src\\github.com目录下

2，进入$GOPATH\\src\\github.com\\go-swagger\\go-swagger\\cmd>  下执行**go install ./swagger，这时候你的**$GOPATH\\bin目录下会生成一个swagger。exe文件，比如我这：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70][]

环境搞好了，接下来进入到项目中，给对应模块加swagger需要的注释：

1，main.go中增加如下内容

// +build go1.13
    //go:generate swagger generate spec -o swagger.json
    
    // Package main wl-COMS API.
    // 		Version: 0.0.1
    //		Schemes: http, https
    //		Host: localhost:8000
    //		BasePath: /api
    //
    //		Consumes:
    //		- application/json
    //		- application/x-www-form-urlencoded
    //		- multipart/form-data
    //
    //		Produces:
    //		- application/json
    //
    //      Security:
    //      - api_key:
    //
    //      SecurityDefinitions:
    //      api_key:
    //          type: apiKey
    //          name: Authorization
    //          in: header
    // swagger:meta
    package main

接着给需要生成的路由模块加下swagger可以识别的注释，比如我以customer模块操作，如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 1][]

要特别注意的是书写格式及其对应，注意URL的/拼接的参数在注释为\{ID\}。

其中接口传参和响应设定写在swagger.go文件中（该文件在路由模块目录下自行创建）我这只操作了customer模块所以只在customer的路由下增加了：

![20200118233530876.png][]

内容如下：

package customer
    
    import "gin-coms/model"
    
    // region parameter		以下是请求SDK时请求参数的构造
    
    // ListCustomerParameter
    // swagger:parameters ListCustomer
    type ListCustomerParameter struct {
    
    	// required: true
    	// in: header
    	Auth string `json:"auth"`	// 不考虑其实际意义，旨在实践以header的方式取参数
    }
    
    // OperateCustomerParameter
    // swagger:parameters CreateCustomer UpdateCustomer
    type OperateCustomerParameter struct {
    	// required: true
    	// in: body
    	Customer model.Customer `json:"customer"`	// 请求体中的参数
    
    	// required: true
    	// in: header
    	Auth string `json:"auth"`	// 不考虑其实际意义，旨在实践以header的方式取参数
    }
    
    
    // DetailCustomerParameter
    // swagger:parameters DetailCustomer
    type DetailCustomerParameter struct {
    	// required: true
    	// in: path
    	ID string
    
    	// required: true
    	// in: header
    	Auth string `json:"auth"`	// 不考虑其实际意义，旨在实践以header的方式取参数
    }
    
    // endregion
    
    // region response  以下是SDK返回的响应的构造，其中EmptyCustomerResponse这个可以用在DELETE 的接口上
    
    // EmptyCustomerResponse
    // swagger:response EmptyCustomerResponse
    type EmptySecretResponse struct {
    	// in: body
    	Body struct {
    	}
    }
    
    // ListCustomerResponse
    // swagger:response ListCustomerResponse
    type ListCustomerResponse struct {
    	// in: body
    	Body struct {
    		Data []model.Customer `json:"data"`
    	}
    }
    
    // OpCustomerResponse
    // swagger:response OpCustomerResponse
    type OpCustomerResponse struct {
    	// in: body
    	Body struct {
    		Data model.Customer `json:"data"`
    	}
    }
    
    // endregion

拿ListCustomer这个接口为例解释一下这个怎么写：定义ListCustomerParameter结构体，给接口处理器ListCustomer后拼接Parameter作为结构体名称；参数为这个接口需要的参数，如果是对象就写对象，在header中的话就写header；必须传的参数需要加// required: true；响应中的定义一样，结构体命名就是给接口处理器ListCustomer后拼接Response；

比如CreateCustomer 这个接口，他的传参在请求体中所以写了in body。

执行main文件的命令按钮：

![20200118230805100.png][]

点击后别急，等控制台的红灯自动灭掉，这时候看看项目根目录，生成了一个swagger.json文件~，如图：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 2][]

已经离成功越来越近了~

## 生成对应语言的SDK ##

将swagger.json的内容复制到[http://editor.swagger.io/][http_editor.swagger.io]的左侧栏中，如图：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 3][]

**滑动鼠标滚轮等左侧内容可以上下自如的滑动后，再点击生成client那个按钮**，选python语言（**你如果需要生成其他语言的SDK直接点选对应的即可**），浏览器会生成一个名为python-client-generated.zip的文件

解压后目录如下：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 4][]

## 生成后怎么调用验证 ##

此处我以简便的方式来调用一下看看：

先启动你的go项目，比如我写的这个是一个基于gin的项目，启动起来，然后将swagger\_client这个目录复制到你的python项目，写如下几行代码：

# -*- coding: UTF-8 -*-
    
    from swagger_client.api.customer_api import CustomerApi
    from swagger_client.api_client import ApiClient
    from swagger_client.configuration import Configuration
    
    c = Configuration()
    api_client = ApiClient(c)
    ins = CustomerApi(api_client)
    res = ins.list_customer(auth="我是岚总")
    
    print res

run一下这个py文件看看结果：

![20200118225913281.png][]

来go这边看看控制台：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 5][]

可以再试试创建接口：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 6][]

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 7][]

大功告成！！！

你如果对生成你需要的语言的SDK不清楚怎么调用它，可以看看docs目录。在生成的sdk里面有个目录叫docs，比如我这以customer为例，看看CustomerApi.md这个文件的这一部分：

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 8][]

这块所写的就是调用示例，照着示例来写就可以了。

### **相逢即是有缘，原创不易，如果对你有帮助或者解决了你的问题，那么可以高抬贵手点个赞哦！** ###

### **再会~** ###

[https_gitlab.com_wanglan_gin-coms.git]: https://gitlab.com/wanglan/gin-coms.git
[https_download.csdn.net_download_HYZX_9987_12115864]: https://download.csdn.net/download/HYZX_9987/12115864
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20200118230513483.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/2020011823334594.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[20200118233530876.png]: https://img-blog.csdnimg.cn/20200118233530876.png
[20200118230805100.png]: https://img-blog.csdnimg.cn/20200118230805100.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/2020011823094247.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[http_editor.swagger.io]: http://editor.swagger.io/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20200118225435867.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20200118225613602.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[20200118225913281.png]: https://img-blog.csdnimg.cn/20200118225913281.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20200118232014688.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 6]: https://img-blog.csdnimg.cn/20200119094133594.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 7]: https://img-blog.csdnimg.cn/2020011909414439.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ_size_16_color_FFFFFF_t_70 8]: https://img-blog.csdnimg.cn/20200119145619825.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9sYW42MTkzLmJsb2cuY3Nkbi5uZXQ=,size_16,color_FFFFFF,t_70