首页 文章

混淆从proto文件创建swagger.json文件

提问于
浏览
2

我已经创建了一个原型文件,其中包含我打算生成的REST Web服务的所有必要消息和rpc函数 . 使用protoc-gen-swagger插件我已经设法将该原型文件编译成swagger.json文件并且一切看起来都很好,除了两件事,我似乎无法解决 .

  • swagger.json文件中的所有定义都以我的proto文件包的名称为前缀 . 有没有办法摆脱这个?

  • 我的消息的所有字段都是“可选的” . 它们没有明确指定,但它们没有被指定为“必需”,根据定义,它们是可选的 . Proto3不再支持必需/可选/重复,但即使我使用Proto2并添加这些关键字,它似乎也不会影响swagger.json输出 . 如何在我的proto文件中指定需要一个字段,以便protoc-gen-swagger将所需的部分添加到json输出?

以下是一个非常基本的原型文件示例:

webservice.proto

syntax = "proto3";
package mypackage;
import "google/api/annotations.proto";

service MyAPIWebService {
    rpc MyFunc (MyMessage) returns (MyResponse) {
        option (google.api.http) = {
            post: "/message"
            body: "*"
        };
    }
}

message MyMessage {
    string MyString = 1;
    int64 MyInt = 2;
}

message MyResponse {
    string MyString = 1;
}

然后使用以下命令将其编译为swagger.json文件:

protoc -I . -I“%GOPATH%/ src / github.com / grpc-ecosystem / grpc-gateway / third_party / googleapis”--swagger_out = logtostderr = true: . webservice.proto

产生以下输出: webservice.swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "webservice.proto",
    "version": "version not set"
  },
  "schemes": [
    "http",
    "https"
  ],
  "consumes": [
    "application/json"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/message": {
      "post": {
        "operationId": "MyFunc",
        "responses": {
          "200": {
            "description": "",
            "schema": {
              "$ref": "#/definitions/mypackageMyResponse"
            }
          }
        },
        "parameters": [
          {
            "name": "body",
            "in": "body",
            "required": true,
            "schema": {
              "$ref": "#/definitions/mypackageMyMessage"
            }
          }
        ],
        "tags": [
          "MyAPIWebService"
        ]
      }
    }
  },
  "definitions": {
    "mypackageMyMessage": {
      "type": "object",
      "properties": {
        "MyString": {
          "type": "string"
        },
        "MyInt": {
          "type": "string",
          "format": "int64"
        }
      }
    },
    "mypackageMyResponse": {
      "type": "object",
      "properties": {
        "MyString": {
          "type": "string"
        }
      }
    }
  }
}
  • 请注意原型文件中的 MyMessageMyResponse 如何转换为json文件中的 mypackageMyMessagemypackageMyResponse .

  • 如果我想要,例如,MyMessage:MyString是必需的,我必须在“定义”中的“mypackageMyMessage”部分添加一个部分,如下所示:

“必需”:[“MyString”]

如果有一种方法可以在proto文件中指定,我肯定更喜欢这样我每次编译时都不必手动编辑json文件 .

1 回答

  • 3

    在这里发布给遇到此问题的其他人寻找相同的信息 .


    UPDATE 这是代码定义如何创建定义的地方 .

    https://github.com/grpc-ecosystem/grpc-gateway/blob/master/protoc-gen-swagger/genswagger/template.go#L859


    这是您可以根据需要表示字段的方法 - 为您的消息定义添加自定义选项:

    message MyMessage {
        option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
            json_schema: {
                title: "MyMessage"
                description: "Does something neat"
                required: ["MyString"]
            }
        };
    
        string MyString = 1;
        int64 MyInt = 2;
    }
    

相关问题