如何用结构体生成Swagger JSON/TOML并上传至Yapi实现共享？

一、仅靠结构体生成Swagger文件 #

完全可以只基于结构体生成Swagger JSON/TOML，不用写接口函数：

• 以Go为例，用swag工具就能实现。给结构体和字段加符合Swagger规范的注释就行，比如：

  // UserRequest TCP通信的用户请求结构体
  // @Description 该结构体用于TCP协议下的用户请求数据交互
  type UserRequest struct {
      // 用户唯一标识ID
      UserID int64 `json:"user_id" swagger:"description:用户系统内唯一ID"`
      // 用户登录账号名
      Username string `json:"username" swagger:"description:用户登录使用的账号名称"`
  }
  

  执行swag init命令，就能生成包含结构体定义的Swagger文件，生成时指定结构体所在的包即可，不用管有没有HTTP接口函数。
• 其他语言也有对应工具：比如Python用drf-yasg基于数据类/序列化器生成；Java用springdoc-openapi基于实体类生成，核心都是通过给结构体加注释生成Swagger定义。

二、适配Yapi的HTTP接口要求 #

Yapi必须要有路径和HTTP方法，你可以虚拟一个接口来承载结构体：

• 生成Swagger文件后，手动加一个虚拟的HTTP路径（比如/tcp-proto/user-request），随便选个方法（比如POST），把你的结构体设为这个接口的请求体或响应体。示例Swagger片段：

  {
    "paths": {
      "/tcp-proto/user-request": {
        "post": {
          "summary": "TCP协议用户请求结构体定义",
          "requestBody": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserRequest"
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "仅用于展示TCP协议的JSON数据结构"
            }
          }
        }
      }
    },
    "components": {
      "schemas": {
        "UserRequest": {
          "type": "object",
          "properties": {
            "user_id": {
              "type": "integer",
              "format": "int64",
              "description": "用户系统内唯一ID"
            },
            "username": {
              "type": "string",
              "description": "用户登录使用的账号名称"
            }
          }
        }
      }
    }
  }
  

• 把修改后的Swagger文件上传到Yapi，其他人就能在Yapi里看到完整的JSON proto结构，虽然是虚拟接口，但核心的数据定义完全能正常共享。

三、更简单的替代方案 #

要是不想折腾Swagger生成，直接在Yapi的「数据管理」模块手动创建JSON Schema，把TCP协议用的结构体对应的JSON结构定义进去，同样能实现共享，省去生成和修改Swagger的步骤。

内容的提问来源于stack exchange，提问作者petrie