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

2. 创建e-food文件，并初始化项目

   mkdir e-food
   go mod init e-food
   

3. 生成服务端代码

   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

0x05 参考

go-swagger

Go-Swagger : A Go Web Framework Worth Learning

Go-Swagger : Structuring & Implementing APIs