Go-Swagger：Go Web框架
0x01 Swagger 与 OpenAPI的区别
- OpenAPI是一个API规范，Swagger是实现规范的工具
0x02 安装Swagger 工具
安装 Swagger 工具
go-swagger 通过 swagger 命令行工具来完成其功能，swagger 安装方法如下：
$ go get -u github.com/go-swagger/go-swagger/cmd/swagger
$ swagger version
version: v0.30.4
0x03 Swagger 命令行工具介绍
-
diff对比两个swagger文档的差异 -
expand展开swagger定义文档中的$ref -
flatten展开swagger文档 -
generate生成swagger文档、客户端代码、服务端代码等 -
ini初始化一个swgger定义文档，初始化时可以指定一些配置 -
mix合并swagger文档 -
serv启动HTTP服务，以查看swagger文档 -
validate验证swagger定义文件是否正确 -
version打印swager 命令版本
0x04 根据swagger规范生成服务器
按照OpenAPI规范格式创建一个swagger.yaml文件。你可以参考 Swagger Editor。
1.我们将首先创建一个名为e-food的网站。通过GET请求获取菜单数据
swagger: '2.0'
info:
version: '1.0.0'
title: E-Food
schemes: [http]
host: e-food.com
basePath: /v1
consumes: [application/json]
produces: [application/json]
paths:
/categories:
get:
tags: [menu]
summary: 'Get menu items for the app'
description: 'It returns a list of nested objects which contains all categories and sub-categories required to create menu'
operationId: CategoryList
responses:
200:
description: 'List of Categories'
schema:
$ref: '#/definitions/Categories'
400:
description: Bad Request
404:
description: Categories Not Found
500:
schema:
type: string
description: Server Error
definitions:
Categories:
type: array
items:
$ref: '#/definitions/Category'
Category:
type: object
properties:
bcId:
type: integer
bcName:
type: string
bcImageUrl:
type: string
bcIsActive:
type: boolean
subCategories:
type: array
items:
$ref: '#/definitions/SubCategory'
SubCategory:
type: object
properties:
scId:
type: integer
scName:
type: string
scImageUrl:
type: string
scIsActive:
type: boolean
-
创建
e-food文件，并初始化项目mkdir e-food go mod init e-food
-
生成服务端代码
swagger generate server -f api/swagger.yaml --default-scheme http
image-20230212215742917.png
以下swagger生成的文件：
-
e_food_api.go这个文件包含url路径和它在initHandlerCache()函数下的处理程序。 -
configure_e_food.go在这个文件中，我们需要关注configureAPI(api *operations.EFoodAPI)，它包含API处理程序与我们自己的业务实现的分配。 -
category_list.go它包含CategoryListHandler接口，其中有Handler(CatergoryParams) middleware.Responder，将由开发人员实现。
花点时间熟悉这些文件，每次你运行swagger.yaml的swagger命令时，其中一些文件都会被覆盖。swagger会在这些文件中添加以下注释。
// Code generated by go-swagger; DO NOT EDIT.
4.创建handlers文件夹，并创建get_categories.go 文件
image-20230212220449367.png
实现如下：
package handlers
import (
"e-food/models"
"e-food/restapi/operations/menu"
"github.com/go-openapi/runtime/middleware"
)
type menuListImpl struct{}
func NewMenuCategoryListHandler() menu.CategoryListHandler {
return &menuListImpl{}
}
func (impl *menuListImpl) Handle(params menu.CategoryListParams) middleware.Responder {
responseVal := &models.Categories{
&models.Category{
BcID: 2001,
BcName: "Fruits",
BcIsActive: true,
BcImageURL: "",
SubCategories: []*models.SubCategory{
{
ScID: 1002,
ScName: "Apple",
ScImageURL: "",
ScIsActive: true,
},
},
},
}
return menu.NewCategoryListOK().WithPayload(*responseVal)
}
我们创建了一个结构menuListImpl，通过实现Handler()函数来实现CategoryListHandler。Handler()函数将被调用，所有的参数都是使用swagger生成的代码定义的。
我们创建了NewMenuCategoryListHandler()，它返回一个menuListImpl的实例（已经实现了接口）。
正如swagger.yaml文件中所定义的，我们可以访问models.Categories及其相关属性。我们使用这个models.Categories来创建一个返回对象，这就是我们在yaml文件中定义的返回类型。
responses:
200:
description: 'List of Categories'
schema:
$ref: '#/definitions/Categories'
5.在最后一步，我们要整合这个处理程序，以便在端点被击中时调用它。要做到这一点，我们需要回到configure_e_food.go文件和下面configureAPI()函数中的代码。
api.MenuCategoryListHandler = handlers.NewMenuCategoryListHandler()
image-20230212220723507.png
5.在本地8080端口运行应用程序
go run cmd\e-food-server\main.go --scheme http --port=8080
image-20230212220757439.png
