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

 

人生如梦  一樽还酹江月

目录

go方面需要做的准备

生成对应语言的SDK

生成后怎么调用验证

提示：生成哪种语言的SDK只是本文的其中一步，具体哪种语言可以选择，没有任何影响；

源码已提交，代码地址：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)，把文件放到你的$GOPATH\src\github.com目录下

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

环境搞好了，接下来进入到项目中，给对应模块加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模块操作，如下：

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

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

内容如下：

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文件的命令按钮：

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

已经离成功越来越近了~

生成对应语言的SDK

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

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

解压后目录如下：

生成后怎么调用验证

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

先启动你的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文件看看结果：

来go这边看看控制台：

可以再试试创建接口：

大功告成！！！

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

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

 

 

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

再会~