prometheus/vendor/github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/genswagger/template.go

2009 lines
64 KiB
Go
Raw Normal View History

package genswagger
import (
"bytes"
"encoding/json"
"fmt"
"io/ioutil"
"os"
"reflect"
"regexp"
"sort"
"strconv"
"strings"
"sync"
"text/template"
"github.com/golang/glog"
"github.com/golang/protobuf/jsonpb"
"github.com/golang/protobuf/proto"
pbdescriptor "github.com/golang/protobuf/protoc-gen-go/descriptor"
structpb "github.com/golang/protobuf/ptypes/struct"
"github.com/grpc-ecosystem/grpc-gateway/internal/casing"
"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway/descriptor"
swagger_options "github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/options"
)
var wktSchemas = map[string]schemaCore{
".google.protobuf.Timestamp": schemaCore{
Type: "string",
Format: "date-time",
},
".google.protobuf.Duration": schemaCore{
Type: "string",
},
".google.protobuf.StringValue": schemaCore{
Type: "string",
},
".google.protobuf.BytesValue": schemaCore{
Type: "string",
Format: "byte",
},
".google.protobuf.Int32Value": schemaCore{
Type: "integer",
Format: "int32",
},
".google.protobuf.UInt32Value": schemaCore{
Type: "integer",
Format: "int64",
},
".google.protobuf.Int64Value": schemaCore{
Type: "string",
Format: "int64",
},
".google.protobuf.UInt64Value": schemaCore{
Type: "string",
Format: "uint64",
},
".google.protobuf.FloatValue": schemaCore{
Type: "number",
Format: "float",
},
".google.protobuf.DoubleValue": schemaCore{
Type: "number",
Format: "double",
},
".google.protobuf.BoolValue": schemaCore{
Type: "boolean",
Format: "boolean",
},
".google.protobuf.Empty": schemaCore{},
".google.protobuf.Struct": schemaCore{
Type: "object",
},
".google.protobuf.Value": schemaCore{
Type: "object",
},
".google.protobuf.ListValue": schemaCore{
Type: "array",
Items: (*swaggerItemsObject)(&schemaCore{
Type: "object",
}),
},
".google.protobuf.NullValue": schemaCore{
Type: "string",
},
}
func listEnumNames(enum *descriptor.Enum) (names []string) {
for _, value := range enum.GetValue() {
names = append(names, value.GetName())
}
return names
}
func listEnumNumbers(enum *descriptor.Enum) (numbers []string) {
for _, value := range enum.GetValue() {
numbers = append(numbers, strconv.Itoa(int(value.GetNumber())))
}
return
}
func getEnumDefault(enum *descriptor.Enum) string {
for _, value := range enum.GetValue() {
if value.GetNumber() == 0 {
return value.GetName()
}
}
return ""
}
// messageToQueryParameters converts a message to a list of swagger query parameters.
func messageToQueryParameters(message *descriptor.Message, reg *descriptor.Registry, pathParams []descriptor.Parameter) (params []swaggerParameterObject, err error) {
for _, field := range message.Fields {
p, err := queryParams(message, field, "", reg, pathParams)
if err != nil {
return nil, err
}
params = append(params, p...)
}
return params, nil
}
// queryParams converts a field to a list of swagger query parameters recursively through the use of nestedQueryParams.
func queryParams(message *descriptor.Message, field *descriptor.Field, prefix string, reg *descriptor.Registry, pathParams []descriptor.Parameter) (params []swaggerParameterObject, err error) {
return nestedQueryParams(message, field, prefix, reg, pathParams, map[string]bool{})
}
// nestedQueryParams converts a field to a list of swagger query parameters recursively.
// This function is a helper function for queryParams, that keeps track of cyclical message references
// through the use of
// touched map[string]bool
// If a cycle is discovered, an error is returned, as cyclical data structures aren't allowed
// in query parameters.
func nestedQueryParams(message *descriptor.Message, field *descriptor.Field, prefix string, reg *descriptor.Registry, pathParams []descriptor.Parameter, touched map[string]bool) (params []swaggerParameterObject, err error) {
// make sure the parameter is not already listed as a path parameter
for _, pathParam := range pathParams {
if pathParam.Target == field {
return nil, nil
}
}
schema := schemaOfField(field, reg, nil)
fieldType := field.GetTypeName()
if message.File != nil {
comments := fieldProtoComments(reg, message, field)
if err := updateSwaggerDataFromComments(reg, &schema, message, comments, false); err != nil {
return nil, err
}
}
isEnum := field.GetType() == pbdescriptor.FieldDescriptorProto_TYPE_ENUM
items := schema.Items
if schema.Type != "" || isEnum {
if schema.Type == "object" {
return nil, nil // TODO: currently, mapping object in query parameter is not supported
}
if items != nil && (items.Type == "" || items.Type == "object") && !isEnum {
return nil, nil // TODO: currently, mapping object in query parameter is not supported
}
desc := schema.Description
if schema.Title != "" { // merge title because title of parameter object will be ignored
desc = strings.TrimSpace(schema.Title + ". " + schema.Description)
}
// verify if the field is required
required := false
for _, fieldName := range schema.Required {
if fieldName == field.GetName() {
required = true
break
}
}
param := swaggerParameterObject{
Description: desc,
In: "query",
Default: schema.Default,
Type: schema.Type,
Items: schema.Items,
Format: schema.Format,
Required: required,
}
if param.Type == "array" {
param.CollectionFormat = "multi"
}
if reg.GetUseJSONNamesForFields() {
param.Name = prefix + field.GetJsonName()
} else {
param.Name = prefix + field.GetName()
}
if isEnum {
enum, err := reg.LookupEnum("", fieldType)
if err != nil {
return nil, fmt.Errorf("unknown enum type %s", fieldType)
}
if items != nil { // array
param.Items = &swaggerItemsObject{
Type: "string",
Enum: listEnumNames(enum),
}
if reg.GetEnumsAsInts() {
param.Items.Type = "integer"
param.Items.Enum = listEnumNumbers(enum)
}
} else {
param.Type = "string"
param.Enum = listEnumNames(enum)
param.Default = getEnumDefault(enum)
if reg.GetEnumsAsInts() {
param.Type = "integer"
param.Enum = listEnumNumbers(enum)
param.Default = "0"
}
}
valueComments := enumValueProtoComments(reg, enum)
if valueComments != "" {
param.Description = strings.TrimLeft(param.Description+"\n\n "+valueComments, "\n")
}
}
return []swaggerParameterObject{param}, nil
}
// nested type, recurse
msg, err := reg.LookupMsg("", fieldType)
if err != nil {
return nil, fmt.Errorf("unknown message type %s", fieldType)
}
// Check for cyclical message reference:
isCycle := touched[*msg.Name]
if isCycle {
return nil, fmt.Errorf("Recursive types are not allowed for query parameters, cycle found on %q", fieldType)
}
// Update map with the massage name so a cycle further down the recursive path can be detected.
touched[*msg.Name] = true
for _, nestedField := range msg.Fields {
var fieldName string
if reg.GetUseJSONNamesForFields() {
fieldName = field.GetJsonName()
} else {
fieldName = field.GetName()
}
p, err := nestedQueryParams(msg, nestedField, prefix+fieldName+".", reg, pathParams, touched)
if err != nil {
return nil, err
}
params = append(params, p...)
}
return params, nil
}
// findServicesMessagesAndEnumerations discovers all messages and enums defined in the RPC methods of the service.
func findServicesMessagesAndEnumerations(s []*descriptor.Service, reg *descriptor.Registry, m messageMap, ms messageMap, e enumMap, refs refMap) {
for _, svc := range s {
for _, meth := range svc.Methods {
// Request may be fully included in query
{
swgReqName, ok := fullyQualifiedNameToSwaggerName(meth.RequestType.FQMN(), reg)
if !ok {
glog.Errorf("couldn't resolve swagger name for FQMN '%v'", meth.RequestType.FQMN())
continue
}
if _, ok := refs[fmt.Sprintf("#/definitions/%s", swgReqName)]; ok {
if !skipRenderingRef(meth.RequestType.FQMN()) {
m[swgReqName] = meth.RequestType
}
}
}
swgRspName, ok := fullyQualifiedNameToSwaggerName(meth.ResponseType.FQMN(), reg)
if !ok && !skipRenderingRef(meth.ResponseType.FQMN()) {
glog.Errorf("couldn't resolve swagger name for FQMN '%v'", meth.ResponseType.FQMN())
continue
}
findNestedMessagesAndEnumerations(meth.RequestType, reg, m, e)
if !skipRenderingRef(meth.ResponseType.FQMN()) {
m[swgRspName] = meth.ResponseType
if meth.GetServerStreaming() {
streamError, runtimeStreamError, err := lookupMsgAndSwaggerName(".grpc.gateway.runtime", "StreamError", reg)
if err != nil {
glog.Error(err)
} else {
glog.V(1).Infof("StreamError: %v", streamError)
glog.V(1).Infof("StreamError FQMN: %s", runtimeStreamError)
m[runtimeStreamError] = streamError
findNestedMessagesAndEnumerations(streamError, reg, m, e)
}
ms[swgRspName] = meth.ResponseType
}
}
findNestedMessagesAndEnumerations(meth.ResponseType, reg, m, e)
}
}
}
// findNestedMessagesAndEnumerations those can be generated by the services.
func findNestedMessagesAndEnumerations(message *descriptor.Message, reg *descriptor.Registry, m messageMap, e enumMap) {
// Iterate over all the fields that
for _, t := range message.Fields {
fieldType := t.GetTypeName()
// If the type is an empty string then it is a proto primitive
if fieldType != "" {
if _, ok := m[fieldType]; !ok {
msg, err := reg.LookupMsg("", fieldType)
if err != nil {
enum, err := reg.LookupEnum("", fieldType)
if err != nil {
panic(err)
}
e[fieldType] = enum
continue
}
m[fieldType] = msg
findNestedMessagesAndEnumerations(msg, reg, m, e)
}
}
}
}
func skipRenderingRef(refName string) bool {
_, ok := wktSchemas[refName]
return ok
}
func renderMessagesAsDefinition(messages messageMap, d swaggerDefinitionsObject, reg *descriptor.Registry, customRefs refMap) {
for name, msg := range messages {
swgName, ok := fullyQualifiedNameToSwaggerName(msg.FQMN(), reg)
if !ok {
panic(fmt.Sprintf("can't resolve swagger name from '%v'", msg.FQMN()))
}
if skipRenderingRef(name) {
continue
}
if opt := msg.GetOptions(); opt != nil && opt.MapEntry != nil && *opt.MapEntry {
continue
}
schema := swaggerSchemaObject{
schemaCore: schemaCore{
Type: "object",
},
}
msgComments := protoComments(reg, msg.File, msg.Outers, "MessageType", int32(msg.Index))
if err := updateSwaggerDataFromComments(reg, &schema, msg, msgComments, false); err != nil {
panic(err)
}
opts, err := extractSchemaOptionFromMessageDescriptor(msg.DescriptorProto)
if err != nil {
panic(err)
}
if opts != nil {
protoSchema := swaggerSchemaFromProtoSchema(opts, reg, customRefs, msg)
// Warning: Make sure not to overwrite any fields already set on the schema type.
schema.ExternalDocs = protoSchema.ExternalDocs
schema.ReadOnly = protoSchema.ReadOnly
schema.MultipleOf = protoSchema.MultipleOf
schema.Maximum = protoSchema.Maximum
schema.ExclusiveMaximum = protoSchema.ExclusiveMaximum
schema.Minimum = protoSchema.Minimum
schema.ExclusiveMinimum = protoSchema.ExclusiveMinimum
schema.MaxLength = protoSchema.MaxLength
schema.MinLength = protoSchema.MinLength
schema.Pattern = protoSchema.Pattern
schema.Default = protoSchema.Default
schema.MaxItems = protoSchema.MaxItems
schema.MinItems = protoSchema.MinItems
schema.UniqueItems = protoSchema.UniqueItems
schema.MaxProperties = protoSchema.MaxProperties
schema.MinProperties = protoSchema.MinProperties
schema.Required = protoSchema.Required
if protoSchema.schemaCore.Type != "" || protoSchema.schemaCore.Ref != "" {
schema.schemaCore = protoSchema.schemaCore
}
if protoSchema.Title != "" {
schema.Title = protoSchema.Title
}
if protoSchema.Description != "" {
schema.Description = protoSchema.Description
}
if protoSchema.Example != nil {
schema.Example = protoSchema.Example
}
}
for _, f := range msg.Fields {
fieldValue := schemaOfField(f, reg, customRefs)
comments := fieldProtoComments(reg, msg, f)
if err := updateSwaggerDataFromComments(reg, &fieldValue, f, comments, false); err != nil {
panic(err)
}
kv := keyVal{Value: fieldValue}
if reg.GetUseJSONNamesForFields() {
kv.Key = f.GetJsonName()
} else {
kv.Key = f.GetName()
}
if schema.Properties == nil {
schema.Properties = &swaggerSchemaObjectProperties{}
}
*schema.Properties = append(*schema.Properties, kv)
}
d[swgName] = schema
}
}
// schemaOfField returns a swagger Schema Object for a protobuf field.
func schemaOfField(f *descriptor.Field, reg *descriptor.Registry, refs refMap) swaggerSchemaObject {
const (
singular = 0
array = 1
object = 2
)
var (
core schemaCore
aggregate int
)
fd := f.FieldDescriptorProto
if m, err := reg.LookupMsg("", f.GetTypeName()); err == nil {
if opt := m.GetOptions(); opt != nil && opt.MapEntry != nil && *opt.MapEntry {
fd = m.GetField()[1]
aggregate = object
}
}
if fd.GetLabel() == pbdescriptor.FieldDescriptorProto_LABEL_REPEATED {
aggregate = array
}
var props *swaggerSchemaObjectProperties
switch ft := fd.GetType(); ft {
case pbdescriptor.FieldDescriptorProto_TYPE_ENUM, pbdescriptor.FieldDescriptorProto_TYPE_MESSAGE, pbdescriptor.FieldDescriptorProto_TYPE_GROUP:
if wktSchema, ok := wktSchemas[fd.GetTypeName()]; ok {
core = wktSchema
if fd.GetTypeName() == ".google.protobuf.Empty" {
props = &swaggerSchemaObjectProperties{}
}
} else {
swgRef, ok := fullyQualifiedNameToSwaggerName(fd.GetTypeName(), reg)
if !ok {
panic(fmt.Sprintf("can't resolve swagger ref from typename '%v'", fd.GetTypeName()))
}
core = schemaCore{
Ref: "#/definitions/" + swgRef,
}
if refs != nil {
refs[fd.GetTypeName()] = struct{}{}
}
}
default:
ftype, format, ok := primitiveSchema(ft)
if ok {
core = schemaCore{Type: ftype, Format: format}
} else {
core = schemaCore{Type: ft.String(), Format: "UNKNOWN"}
}
}
ret := swaggerSchemaObject{}
switch aggregate {
case array:
ret = swaggerSchemaObject{
schemaCore: schemaCore{
Type: "array",
Items: (*swaggerItemsObject)(&core),
},
}
case object:
ret = swaggerSchemaObject{
schemaCore: schemaCore{
Type: "object",
},
AdditionalProperties: &swaggerSchemaObject{Properties: props, schemaCore: core},
}
default:
ret = swaggerSchemaObject{
schemaCore: core,
Properties: props,
}
}
if j, err := extractJSONSchemaFromFieldDescriptor(fd); err == nil {
updateSwaggerObjectFromJSONSchema(&ret, j, reg, f)
}
return ret
}
// primitiveSchema returns a pair of "Type" and "Format" in JSON Schema for
// the given primitive field type.
// The last return parameter is true iff the field type is actually primitive.
func primitiveSchema(t pbdescriptor.FieldDescriptorProto_Type) (ftype, format string, ok bool) {
switch t {
case pbdescriptor.FieldDescriptorProto_TYPE_DOUBLE:
return "number", "double", true
case pbdescriptor.FieldDescriptorProto_TYPE_FLOAT:
return "number", "float", true
case pbdescriptor.FieldDescriptorProto_TYPE_INT64:
return "string", "int64", true
case pbdescriptor.FieldDescriptorProto_TYPE_UINT64:
// 64bit integer types are marshaled as string in the default JSONPb marshaler.
// TODO(yugui) Add an option to declare 64bit integers as int64.
//
// NOTE: uint64 is not a predefined format of integer type in Swagger spec.
// So we cannot expect that uint64 is commonly supported by swagger processor.
return "string", "uint64", true
case pbdescriptor.FieldDescriptorProto_TYPE_INT32:
return "integer", "int32", true
case pbdescriptor.FieldDescriptorProto_TYPE_FIXED64:
// Ditto.
return "string", "uint64", true
case pbdescriptor.FieldDescriptorProto_TYPE_FIXED32:
// Ditto.
return "integer", "int64", true
case pbdescriptor.FieldDescriptorProto_TYPE_BOOL:
return "boolean", "boolean", true
case pbdescriptor.FieldDescriptorProto_TYPE_STRING:
// NOTE: in swagger specifition, format should be empty on string type
return "string", "", true
case pbdescriptor.FieldDescriptorProto_TYPE_BYTES:
return "string", "byte", true
case pbdescriptor.FieldDescriptorProto_TYPE_UINT32:
// Ditto.
return "integer", "int64", true
case pbdescriptor.FieldDescriptorProto_TYPE_SFIXED32:
return "integer", "int32", true
case pbdescriptor.FieldDescriptorProto_TYPE_SFIXED64:
return "string", "int64", true
case pbdescriptor.FieldDescriptorProto_TYPE_SINT32:
return "integer", "int32", true
case pbdescriptor.FieldDescriptorProto_TYPE_SINT64:
return "string", "int64", true
default:
return "", "", false
}
}
// renderEnumerationsAsDefinition inserts enums into the definitions object.
func renderEnumerationsAsDefinition(enums enumMap, d swaggerDefinitionsObject, reg *descriptor.Registry) {
for _, enum := range enums {
swgName, ok := fullyQualifiedNameToSwaggerName(enum.FQEN(), reg)
if !ok {
panic(fmt.Sprintf("can't resolve swagger name from FQEN '%v'", enum.FQEN()))
}
enumComments := protoComments(reg, enum.File, enum.Outers, "EnumType", int32(enum.Index))
// it may be necessary to sort the result of the GetValue function.
enumNames := listEnumNames(enum)
defaultValue := getEnumDefault(enum)
valueComments := enumValueProtoComments(reg, enum)
if valueComments != "" {
enumComments = strings.TrimLeft(enumComments+"\n\n "+valueComments, "\n")
}
enumSchemaObject := swaggerSchemaObject{
schemaCore: schemaCore{
Type: "string",
Enum: enumNames,
Default: defaultValue,
},
}
if reg.GetEnumsAsInts() {
enumSchemaObject.Type = "integer"
enumSchemaObject.Format = "int32"
enumSchemaObject.Default = "0"
enumSchemaObject.Enum = listEnumNumbers(enum)
}
if err := updateSwaggerDataFromComments(reg, &enumSchemaObject, enum, enumComments, false); err != nil {
panic(err)
}
d[swgName] = enumSchemaObject
}
}
// Take in a FQMN or FQEN and return a swagger safe version of the FQMN and
// a boolean indicating if FQMN was properly resolved.
func fullyQualifiedNameToSwaggerName(fqn string, reg *descriptor.Registry) (string, bool) {
registriesSeenMutex.Lock()
defer registriesSeenMutex.Unlock()
if mapping, present := registriesSeen[reg]; present {
ret, ok := mapping[fqn]
return ret, ok
}
mapping := resolveFullyQualifiedNameToSwaggerNames(append(reg.GetAllFQMNs(), reg.GetAllFQENs()...), reg.GetUseFQNForSwaggerName())
registriesSeen[reg] = mapping
ret, ok := mapping[fqn]
return ret, ok
}
// Lookup message type by location.name and return a swagger-safe version
// of its FQMN.
func lookupMsgAndSwaggerName(location, name string, reg *descriptor.Registry) (*descriptor.Message, string, error) {
msg, err := reg.LookupMsg(location, name)
if err != nil {
return nil, "", err
}
swgName, ok := fullyQualifiedNameToSwaggerName(msg.FQMN(), reg)
if !ok {
return nil, "", fmt.Errorf("can't map swagger name from FQMN '%v'", msg.FQMN())
}
return msg, swgName, nil
}
// registriesSeen is used to memoise calls to resolveFullyQualifiedNameToSwaggerNames so
// we don't repeat it unnecessarily, since it can take some time.
var registriesSeen = map[*descriptor.Registry]map[string]string{}
var registriesSeenMutex sync.Mutex
// Take the names of every proto and "uniq-ify" them. The idea is to produce a
// set of names that meet a couple of conditions. They must be stable, they
// must be unique, and they must be shorter than the FQN.
//
// This likely could be made better. This will always generate the same names
// but may not always produce optimal names. This is a reasonably close
// approximation of what they should look like in most cases.
func resolveFullyQualifiedNameToSwaggerNames(messages []string, useFQNForSwaggerName bool) map[string]string {
packagesByDepth := make(map[int][][]string)
uniqueNames := make(map[string]string)
hierarchy := func(pkg string) []string {
return strings.Split(pkg, ".")
}
for _, p := range messages {
h := hierarchy(p)
for depth := range h {
if _, ok := packagesByDepth[depth]; !ok {
packagesByDepth[depth] = make([][]string, 0)
}
packagesByDepth[depth] = append(packagesByDepth[depth], h[len(h)-depth:])
}
}
count := func(list [][]string, item []string) int {
i := 0
for _, element := range list {
if reflect.DeepEqual(element, item) {
i++
}
}
return i
}
for _, p := range messages {
if useFQNForSwaggerName {
// strip leading dot from proto fqn
uniqueNames[p] = p[1:]
} else {
h := hierarchy(p)
for depth := 0; depth < len(h); depth++ {
if count(packagesByDepth[depth], h[len(h)-depth:]) == 1 {
uniqueNames[p] = strings.Join(h[len(h)-depth-1:], "")
break
}
if depth == len(h)-1 {
uniqueNames[p] = strings.Join(h, "")
}
}
}
}
return uniqueNames
}
var canRegexp = regexp.MustCompile("{([a-zA-Z][a-zA-Z0-9_.]*).*}")
// Swagger expects paths of the form /path/{string_value} but grpc-gateway paths are expected to be of the form /path/{string_value=strprefix/*}. This should reformat it correctly.
func templateToSwaggerPath(path string, reg *descriptor.Registry, fields []*descriptor.Field, msgs []*descriptor.Message) string {
// It seems like the right thing to do here is to just use
// strings.Split(path, "/") but that breaks badly when you hit a url like
// /{my_field=prefix/*}/ and end up with 2 sections representing my_field.
// Instead do the right thing and write a small pushdown (counter) automata
// for it.
var parts []string
depth := 0
buffer := ""
jsonBuffer := ""
for _, char := range path {
switch char {
case '{':
// Push on the stack
depth++
buffer += string(char)
jsonBuffer = ""
jsonBuffer += string(char)
break
case '}':
if depth == 0 {
panic("Encountered } without matching { before it.")
}
// Pop from the stack
depth--
buffer += string(char)
if reg.GetUseJSONNamesForFields() &&
len(jsonBuffer) > 1 {
jsonSnakeCaseName := string(jsonBuffer[1:])
jsonCamelCaseName := string(lowerCamelCase(jsonSnakeCaseName, fields, msgs))
prev := string(buffer[:len(buffer)-len(jsonSnakeCaseName)-2])
buffer = strings.Join([]string{prev, "{", jsonCamelCaseName, "}"}, "")
jsonBuffer = ""
}
case '/':
if depth == 0 {
parts = append(parts, buffer)
buffer = ""
// Since the stack was empty when we hit the '/' we are done with this
// section.
continue
}
buffer += string(char)
jsonBuffer += string(char)
default:
buffer += string(char)
jsonBuffer += string(char)
break
}
}
// Now append the last element to parts
parts = append(parts, buffer)
// Parts is now an array of segments of the path. Interestingly, since the
// syntax for this subsection CAN be handled by a regexp since it has no
// memory.
for index, part := range parts {
// If part is a resource name such as "parent", "name", "user.name", the format info must be retained.
prefix := canRegexp.ReplaceAllString(part, "$1")
if isResourceName(prefix) {
continue
}
parts[index] = canRegexp.ReplaceAllString(part, "{$1}")
}
return strings.Join(parts, "/")
}
func isResourceName(prefix string) bool {
words := strings.Split(prefix, ".")
l := len(words)
field := words[l-1]
words = strings.Split(field, ":")
field = words[0]
return field == "parent" || field == "name"
}
func renderServices(services []*descriptor.Service, paths swaggerPathsObject, reg *descriptor.Registry, requestResponseRefs, customRefs refMap, msgs []*descriptor.Message) error {
// Correctness of svcIdx and methIdx depends on 'services' containing the services in the same order as the 'file.Service' array.
for svcIdx, svc := range services {
for methIdx, meth := range svc.Methods {
for bIdx, b := range meth.Bindings {
// Iterate over all the swagger parameters
parameters := swaggerParametersObject{}
for _, parameter := range b.PathParams {
var paramType, paramFormat, desc, collectionFormat, defaultValue string
var enumNames []string
var items *swaggerItemsObject
var minItems *int
switch pt := parameter.Target.GetType(); pt {
case pbdescriptor.FieldDescriptorProto_TYPE_GROUP, pbdescriptor.FieldDescriptorProto_TYPE_MESSAGE:
if descriptor.IsWellKnownType(parameter.Target.GetTypeName()) {
if parameter.IsRepeated() {
return fmt.Errorf("only primitive and enum types are allowed in repeated path parameters")
}
schema := schemaOfField(parameter.Target, reg, customRefs)
paramType = schema.Type
paramFormat = schema.Format
desc = schema.Description
defaultValue = schema.Default
} else {
return fmt.Errorf("only primitive and well-known types are allowed in path parameters")
}
case pbdescriptor.FieldDescriptorProto_TYPE_ENUM:
enum, err := reg.LookupEnum("", parameter.Target.GetTypeName())
if err != nil {
return err
}
paramType = "string"
paramFormat = ""
enumNames = listEnumNames(enum)
if reg.GetEnumsAsInts() {
paramType = "integer"
paramFormat = ""
enumNames = listEnumNumbers(enum)
}
schema := schemaOfField(parameter.Target, reg, customRefs)
desc = schema.Description
defaultValue = schema.Default
default:
var ok bool
paramType, paramFormat, ok = primitiveSchema(pt)
if !ok {
return fmt.Errorf("unknown field type %v", pt)
}
schema := schemaOfField(parameter.Target, reg, customRefs)
desc = schema.Description
defaultValue = schema.Default
}
if parameter.IsRepeated() {
core := schemaCore{Type: paramType, Format: paramFormat}
if parameter.IsEnum() {
var s []string
core.Enum = enumNames
enumNames = s
}
items = (*swaggerItemsObject)(&core)
paramType = "array"
paramFormat = ""
collectionFormat = reg.GetRepeatedPathParamSeparatorName()
minItems = new(int)
*minItems = 1
}
if desc == "" {
desc = fieldProtoComments(reg, parameter.Target.Message, parameter.Target)
}
parameterString := parameter.String()
if reg.GetUseJSONNamesForFields() {
parameterString = lowerCamelCase(parameterString, meth.RequestType.Fields, msgs)
}
parameters = append(parameters, swaggerParameterObject{
Name: parameterString,
Description: desc,
In: "path",
Required: true,
Default: defaultValue,
// Parameters in gRPC-Gateway can only be strings?
Type: paramType,
Format: paramFormat,
Enum: enumNames,
Items: items,
CollectionFormat: collectionFormat,
MinItems: minItems,
})
}
// Now check if there is a body parameter
if b.Body != nil {
var schema swaggerSchemaObject
desc := ""
if len(b.Body.FieldPath) == 0 {
schema = swaggerSchemaObject{
schemaCore: schemaCore{},
}
wknSchemaCore, isWkn := wktSchemas[meth.RequestType.FQMN()]
if !isWkn {
err := schema.setRefFromFQN(meth.RequestType.FQMN(), reg)
if err != nil {
return err
}
} else {
schema.schemaCore = wknSchemaCore
// Special workaround for Empty: it's well-known type but wknSchemas only returns schema.schemaCore; but we need to set schema.Properties which is a level higher.
if meth.RequestType.FQMN() == ".google.protobuf.Empty" {
schema.Properties = &swaggerSchemaObjectProperties{}
}
}
} else {
lastField := b.Body.FieldPath[len(b.Body.FieldPath)-1]
schema = schemaOfField(lastField.Target, reg, customRefs)
if schema.Description != "" {
desc = schema.Description
} else {
desc = fieldProtoComments(reg, lastField.Target.Message, lastField.Target)
}
}
if meth.GetClientStreaming() {
desc += " (streaming inputs)"
}
parameters = append(parameters, swaggerParameterObject{
Name: "body",
Description: desc,
In: "body",
Required: true,
Schema: &schema,
})
} else if b.HTTPMethod == "GET" || b.HTTPMethod == "DELETE" {
// add the parameters to the query string
queryParams, err := messageToQueryParameters(meth.RequestType, reg, b.PathParams)
if err != nil {
return err
}
parameters = append(parameters, queryParams...)
}
pathItemObject, ok := paths[templateToSwaggerPath(b.PathTmpl.Template, reg, meth.RequestType.Fields, msgs)]
if !ok {
pathItemObject = swaggerPathItemObject{}
}
methProtoPath := protoPathIndex(reflect.TypeOf((*pbdescriptor.ServiceDescriptorProto)(nil)), "Method")
desc := "A successful response."
var responseSchema swaggerSchemaObject
if b.ResponseBody == nil || len(b.ResponseBody.FieldPath) == 0 {
responseSchema = swaggerSchemaObject{
schemaCore: schemaCore{},
}
// Don't link to a full definition for
// empty; it's overly verbose.
// schema.Properties{} renders it as
// well, without a definition
wknSchemaCore, isWkn := wktSchemas[meth.ResponseType.FQMN()]
if !isWkn {
err := responseSchema.setRefFromFQN(meth.ResponseType.FQMN(), reg)
if err != nil {
return err
}
} else {
responseSchema.schemaCore = wknSchemaCore
// Special workaround for Empty: it's well-known type but wknSchemas only returns schema.schemaCore; but we need to set schema.Properties which is a level higher.
if meth.ResponseType.FQMN() == ".google.protobuf.Empty" {
responseSchema.Properties = &swaggerSchemaObjectProperties{}
}
}
} else {
// This is resolving the value of response_body in the google.api.HttpRule
lastField := b.ResponseBody.FieldPath[len(b.ResponseBody.FieldPath)-1]
responseSchema = schemaOfField(lastField.Target, reg, customRefs)
if responseSchema.Description != "" {
desc = responseSchema.Description
} else {
desc = fieldProtoComments(reg, lastField.Target.Message, lastField.Target)
}
}
if meth.GetServerStreaming() {
desc += "(streaming responses)"
responseSchema.Type = "object"
swgRef, _ := fullyQualifiedNameToSwaggerName(meth.ResponseType.FQMN(), reg)
responseSchema.Title = "Stream result of " + swgRef
props := swaggerSchemaObjectProperties{
keyVal{
Key: "result",
Value: swaggerSchemaObject{
schemaCore: schemaCore{
Ref: responseSchema.Ref,
},
},
},
}
streamErrDef, hasStreamError := fullyQualifiedNameToSwaggerName(".grpc.gateway.runtime.StreamError", reg)
if hasStreamError {
props = append(props, keyVal{
Key: "error",
Value: swaggerSchemaObject{
schemaCore: schemaCore{
Ref: fmt.Sprintf("#/definitions/%s", streamErrDef)},
},
})
}
responseSchema.Properties = &props
responseSchema.Ref = ""
}
tag := svc.GetName()
if pkg := svc.File.GetPackage(); pkg != "" && reg.IsIncludePackageInTags() {
tag = pkg + "." + tag
}
operationObject := &swaggerOperationObject{
Tags: []string{tag},
Parameters: parameters,
Responses: swaggerResponsesObject{
"200": swaggerResponseObject{
Description: desc,
Schema: responseSchema,
},
},
}
if !reg.GetDisableDefaultErrors() {
errDef, hasErrDef := fullyQualifiedNameToSwaggerName(".grpc.gateway.runtime.Error", reg)
if hasErrDef {
// https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#responses-object
operationObject.Responses["default"] = swaggerResponseObject{
Description: "An unexpected error response",
Schema: swaggerSchemaObject{
schemaCore: schemaCore{
Ref: fmt.Sprintf("#/definitions/%s", errDef),
},
},
}
}
}
operationObject.OperationID = fmt.Sprintf("%s_%s", svc.GetName(), meth.GetName())
if reg.GetSimpleOperationIDs() {
operationObject.OperationID = fmt.Sprintf("%s", meth.GetName())
}
if bIdx != 0 {
// OperationID must be unique in an OpenAPI v2 definition.
operationObject.OperationID += strconv.Itoa(bIdx + 1)
}
// Fill reference map with referenced request messages
for _, param := range operationObject.Parameters {
if param.Schema != nil && param.Schema.Ref != "" {
requestResponseRefs[param.Schema.Ref] = struct{}{}
}
}
methComments := protoComments(reg, svc.File, nil, "Service", int32(svcIdx), methProtoPath, int32(methIdx))
if err := updateSwaggerDataFromComments(reg, operationObject, meth, methComments, false); err != nil {
panic(err)
}
opts, err := extractOperationOptionFromMethodDescriptor(meth.MethodDescriptorProto)
if opts != nil {
if err != nil {
panic(err)
}
operationObject.ExternalDocs = protoExternalDocumentationToSwaggerExternalDocumentation(opts.ExternalDocs, reg, meth)
// TODO(ivucica): this would be better supported by looking whether the method is deprecated in the proto file
operationObject.Deprecated = opts.Deprecated
if opts.Summary != "" {
operationObject.Summary = opts.Summary
}
if opts.Description != "" {
operationObject.Description = opts.Description
}
if len(opts.Tags) > 0 {
operationObject.Tags = make([]string, len(opts.Tags))
copy(operationObject.Tags, opts.Tags)
}
if opts.OperationId != "" {
operationObject.OperationID = opts.OperationId
}
if opts.Security != nil {
newSecurity := []swaggerSecurityRequirementObject{}
if operationObject.Security != nil {
newSecurity = *operationObject.Security
}
for _, secReq := range opts.Security {
newSecReq := swaggerSecurityRequirementObject{}
for secReqKey, secReqValue := range secReq.SecurityRequirement {
if secReqValue == nil {
continue
}
newSecReqValue := make([]string, len(secReqValue.Scope))
copy(newSecReqValue, secReqValue.Scope)
newSecReq[secReqKey] = newSecReqValue
}
if len(newSecReq) > 0 {
newSecurity = append(newSecurity, newSecReq)
}
}
operationObject.Security = &newSecurity
}
if opts.Responses != nil {
for name, resp := range opts.Responses {
// Merge response data into default response if available.
respObj := operationObject.Responses[name]
if resp.Description != "" {
respObj.Description = resp.Description
}
if resp.Schema != nil {
respObj.Schema = swaggerSchemaFromProtoSchema(resp.Schema, reg, customRefs, meth)
}
if resp.Examples != nil {
respObj.Examples = swaggerExamplesFromProtoExamples(resp.Examples)
}
if resp.Extensions != nil {
exts, err := processExtensions(resp.Extensions)
if err != nil {
return err
}
respObj.extensions = exts
}
operationObject.Responses[name] = respObj
}
}
if opts.Extensions != nil {
exts, err := processExtensions(opts.Extensions)
if err != nil {
return err
}
operationObject.extensions = exts
}
if len(opts.Produces) > 0 {
operationObject.Produces = make([]string, len(opts.Produces))
copy(operationObject.Produces, opts.Produces)
}
// TODO(ivucica): add remaining fields of operation object
}
switch b.HTTPMethod {
case "DELETE":
pathItemObject.Delete = operationObject
break
case "GET":
pathItemObject.Get = operationObject
break
case "POST":
pathItemObject.Post = operationObject
break
case "PUT":
pathItemObject.Put = operationObject
break
case "PATCH":
pathItemObject.Patch = operationObject
break
}
paths[templateToSwaggerPath(b.PathTmpl.Template, reg, meth.RequestType.Fields, msgs)] = pathItemObject
}
}
}
// Success! return nil on the error object
return nil
}
// This function is called with a param which contains the entire definition of a method.
func applyTemplate(p param) (*swaggerObject, error) {
// Create the basic template object. This is the object that everything is
// defined off of.
s := swaggerObject{
// Swagger 2.0 is the version of this document
Swagger: "2.0",
Consumes: []string{"application/json"},
Produces: []string{"application/json"},
Paths: make(swaggerPathsObject),
Definitions: make(swaggerDefinitionsObject),
Info: swaggerInfoObject{
Title: *p.File.Name,
Version: "version not set",
},
}
// Loops through all the services and their exposed GET/POST/PUT/DELETE definitions
// and create entries for all of them.
// Also adds custom user specified references to second map.
requestResponseRefs, customRefs := refMap{}, refMap{}
if err := renderServices(p.Services, s.Paths, p.reg, requestResponseRefs, customRefs, p.Messages); err != nil {
panic(err)
}
messages := messageMap{}
streamingMessages := messageMap{}
enums := enumMap{}
if !p.reg.GetDisableDefaultErrors() {
// Add the error type to the message map
runtimeError, swgRef, err := lookupMsgAndSwaggerName(".grpc.gateway.runtime", "Error", p.reg)
if err == nil {
messages[swgRef] = runtimeError
} else {
// just in case there is an error looking up runtimeError
glog.Error(err)
}
}
// Find all the service's messages and enumerations that are defined (recursively)
// and write request, response and other custom (but referenced) types out as definition objects.
findServicesMessagesAndEnumerations(p.Services, p.reg, messages, streamingMessages, enums, requestResponseRefs)
renderMessagesAsDefinition(messages, s.Definitions, p.reg, customRefs)
renderEnumerationsAsDefinition(enums, s.Definitions, p.reg)
// File itself might have some comments and metadata.
packageProtoPath := protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "Package")
packageComments := protoComments(p.reg, p.File, nil, "Package", packageProtoPath)
if err := updateSwaggerDataFromComments(p.reg, &s, p, packageComments, true); err != nil {
panic(err)
}
// There may be additional options in the swagger option in the proto.
spb, err := extractSwaggerOptionFromFileDescriptor(p.FileDescriptorProto)
if err != nil {
panic(err)
}
if spb != nil {
if spb.Swagger != "" {
s.Swagger = spb.Swagger
}
if spb.Info != nil {
if spb.Info.Title != "" {
s.Info.Title = spb.Info.Title
}
if spb.Info.Description != "" {
s.Info.Description = spb.Info.Description
}
if spb.Info.TermsOfService != "" {
s.Info.TermsOfService = spb.Info.TermsOfService
}
if spb.Info.Version != "" {
s.Info.Version = spb.Info.Version
}
if spb.Info.Contact != nil {
if s.Info.Contact == nil {
s.Info.Contact = &swaggerContactObject{}
}
if spb.Info.Contact.Name != "" {
s.Info.Contact.Name = spb.Info.Contact.Name
}
if spb.Info.Contact.Url != "" {
s.Info.Contact.URL = spb.Info.Contact.Url
}
if spb.Info.Contact.Email != "" {
s.Info.Contact.Email = spb.Info.Contact.Email
}
}
if spb.Info.License != nil {
if s.Info.License == nil {
s.Info.License = &swaggerLicenseObject{}
}
if spb.Info.License.Name != "" {
s.Info.License.Name = spb.Info.License.Name
}
if spb.Info.License.Url != "" {
s.Info.License.URL = spb.Info.License.Url
}
}
if spb.Info.Extensions != nil {
exts, err := processExtensions(spb.Info.Extensions)
if err != nil {
return nil, err
}
s.Info.extensions = exts
}
}
if spb.Host != "" {
s.Host = spb.Host
}
if spb.BasePath != "" {
s.BasePath = spb.BasePath
}
if len(spb.Schemes) > 0 {
s.Schemes = make([]string, len(spb.Schemes))
for i, scheme := range spb.Schemes {
s.Schemes[i] = strings.ToLower(scheme.String())
}
}
if len(spb.Consumes) > 0 {
s.Consumes = make([]string, len(spb.Consumes))
copy(s.Consumes, spb.Consumes)
}
if len(spb.Produces) > 0 {
s.Produces = make([]string, len(spb.Produces))
copy(s.Produces, spb.Produces)
}
if spb.SecurityDefinitions != nil && spb.SecurityDefinitions.Security != nil {
if s.SecurityDefinitions == nil {
s.SecurityDefinitions = swaggerSecurityDefinitionsObject{}
}
for secDefKey, secDefValue := range spb.SecurityDefinitions.Security {
var newSecDefValue swaggerSecuritySchemeObject
if oldSecDefValue, ok := s.SecurityDefinitions[secDefKey]; !ok {
newSecDefValue = swaggerSecuritySchemeObject{}
} else {
newSecDefValue = oldSecDefValue
}
if secDefValue.Type != swagger_options.SecurityScheme_TYPE_INVALID {
switch secDefValue.Type {
case swagger_options.SecurityScheme_TYPE_BASIC:
newSecDefValue.Type = "basic"
case swagger_options.SecurityScheme_TYPE_API_KEY:
newSecDefValue.Type = "apiKey"
case swagger_options.SecurityScheme_TYPE_OAUTH2:
newSecDefValue.Type = "oauth2"
}
}
if secDefValue.Description != "" {
newSecDefValue.Description = secDefValue.Description
}
if secDefValue.Name != "" {
newSecDefValue.Name = secDefValue.Name
}
if secDefValue.In != swagger_options.SecurityScheme_IN_INVALID {
switch secDefValue.In {
case swagger_options.SecurityScheme_IN_QUERY:
newSecDefValue.In = "query"
case swagger_options.SecurityScheme_IN_HEADER:
newSecDefValue.In = "header"
}
}
if secDefValue.Flow != swagger_options.SecurityScheme_FLOW_INVALID {
switch secDefValue.Flow {
case swagger_options.SecurityScheme_FLOW_IMPLICIT:
newSecDefValue.Flow = "implicit"
case swagger_options.SecurityScheme_FLOW_PASSWORD:
newSecDefValue.Flow = "password"
case swagger_options.SecurityScheme_FLOW_APPLICATION:
newSecDefValue.Flow = "application"
case swagger_options.SecurityScheme_FLOW_ACCESS_CODE:
newSecDefValue.Flow = "accessCode"
}
}
if secDefValue.AuthorizationUrl != "" {
newSecDefValue.AuthorizationURL = secDefValue.AuthorizationUrl
}
if secDefValue.TokenUrl != "" {
newSecDefValue.TokenURL = secDefValue.TokenUrl
}
if secDefValue.Scopes != nil {
if newSecDefValue.Scopes == nil {
newSecDefValue.Scopes = swaggerScopesObject{}
}
for scopeKey, scopeDesc := range secDefValue.Scopes.Scope {
newSecDefValue.Scopes[scopeKey] = scopeDesc
}
}
if secDefValue.Extensions != nil {
exts, err := processExtensions(secDefValue.Extensions)
if err != nil {
return nil, err
}
newSecDefValue.extensions = exts
}
s.SecurityDefinitions[secDefKey] = newSecDefValue
}
}
if spb.Security != nil {
newSecurity := []swaggerSecurityRequirementObject{}
if s.Security == nil {
newSecurity = []swaggerSecurityRequirementObject{}
} else {
newSecurity = s.Security
}
for _, secReq := range spb.Security {
newSecReq := swaggerSecurityRequirementObject{}
for secReqKey, secReqValue := range secReq.SecurityRequirement {
newSecReqValue := make([]string, len(secReqValue.Scope))
copy(newSecReqValue, secReqValue.Scope)
newSecReq[secReqKey] = newSecReqValue
}
newSecurity = append(newSecurity, newSecReq)
}
s.Security = newSecurity
}
s.ExternalDocs = protoExternalDocumentationToSwaggerExternalDocumentation(spb.ExternalDocs, p.reg, spb)
// Populate all Paths with Responses set at top level,
// preferring Responses already set over those at the top level.
if spb.Responses != nil {
for _, verbs := range s.Paths {
var maps []swaggerResponsesObject
if verbs.Delete != nil {
maps = append(maps, verbs.Delete.Responses)
}
if verbs.Get != nil {
maps = append(maps, verbs.Get.Responses)
}
if verbs.Post != nil {
maps = append(maps, verbs.Post.Responses)
}
if verbs.Put != nil {
maps = append(maps, verbs.Put.Responses)
}
if verbs.Patch != nil {
maps = append(maps, verbs.Patch.Responses)
}
for k, v := range spb.Responses {
for _, respMap := range maps {
if _, ok := respMap[k]; ok {
// Don't overwrite already existing Responses
continue
}
respMap[k] = swaggerResponseObject{
Description: v.Description,
Schema: swaggerSchemaFromProtoSchema(v.Schema, p.reg, customRefs, nil),
Examples: swaggerExamplesFromProtoExamples(v.Examples),
}
}
}
}
}
if spb.Extensions != nil {
exts, err := processExtensions(spb.Extensions)
if err != nil {
return nil, err
}
s.extensions = exts
}
// Additional fields on the OpenAPI v2 spec's "Swagger" object
// should be added here, once supported in the proto.
}
// Finally add any references added by users that aren't
// otherwise rendered.
addCustomRefs(s.Definitions, p.reg, customRefs)
return &s, nil
}
func processExtensions(inputExts map[string]*structpb.Value) ([]extension, error) {
exts := []extension{}
for k, v := range inputExts {
if !strings.HasPrefix(k, "x-") {
return nil, fmt.Errorf("Extension keys need to start with \"x-\": %q", k)
}
ext, err := (&jsonpb.Marshaler{Indent: " "}).MarshalToString(v)
if err != nil {
return nil, err
}
exts = append(exts, extension{key: k, value: json.RawMessage(ext)})
}
sort.Slice(exts, func(i, j int) bool { return exts[i].key < exts[j].key })
return exts, nil
}
// updateSwaggerDataFromComments updates a Swagger object based on a comment
// from the proto file.
//
// First paragraph of a comment is used for summary. Remaining paragraphs of
// a comment are used for description. If 'Summary' field is not present on
// the passed swaggerObject, the summary and description are joined by \n\n.
//
// If there is a field named 'Info', its 'Summary' and 'Description' fields
// will be updated instead.
//
// If there is no 'Summary', the same behavior will be attempted on 'Title',
// but only if the last character is not a period.
func updateSwaggerDataFromComments(reg *descriptor.Registry, swaggerObject interface{}, data interface{}, comment string, isPackageObject bool) error {
if len(comment) == 0 {
return nil
}
// Checks whether the "use_go_templates" flag is set to true
if reg.GetUseGoTemplate() {
comment = goTemplateComments(comment, data, reg)
}
// Figure out what to apply changes to.
swaggerObjectValue := reflect.ValueOf(swaggerObject)
infoObjectValue := swaggerObjectValue.Elem().FieldByName("Info")
if !infoObjectValue.CanSet() {
// No such field? Apply summary and description directly to
// passed object.
infoObjectValue = swaggerObjectValue.Elem()
}
// Figure out which properties to update.
summaryValue := infoObjectValue.FieldByName("Summary")
descriptionValue := infoObjectValue.FieldByName("Description")
readOnlyValue := infoObjectValue.FieldByName("ReadOnly")
if readOnlyValue.Kind() == reflect.Bool && readOnlyValue.CanSet() && strings.Contains(comment, "Output only.") {
readOnlyValue.Set(reflect.ValueOf(true))
}
usingTitle := false
if !summaryValue.CanSet() {
summaryValue = infoObjectValue.FieldByName("Title")
usingTitle = true
}
paragraphs := strings.Split(comment, "\n\n")
// If there is a summary (or summary-equivalent) and it's empty, use the first
// paragraph as summary, and the rest as description.
if summaryValue.CanSet() {
summary := strings.TrimSpace(paragraphs[0])
description := strings.TrimSpace(strings.Join(paragraphs[1:], "\n\n"))
if !usingTitle || (len(summary) > 0 && summary[len(summary)-1] != '.') {
// overrides the schema value only if it's empty
// keep the comment precedence when updating the package definition
if summaryValue.Len() == 0 || isPackageObject {
summaryValue.Set(reflect.ValueOf(summary))
}
if len(description) > 0 {
if !descriptionValue.CanSet() {
return fmt.Errorf("Encountered object type with a summary, but no description")
}
// overrides the schema value only if it's empty
// keep the comment precedence when updating the package definition
if descriptionValue.Len() == 0 || isPackageObject {
descriptionValue.Set(reflect.ValueOf(description))
}
}
return nil
}
}
// There was no summary field on the swaggerObject. Try to apply the
// whole comment into description if the swagger object description is empty.
if descriptionValue.CanSet() {
if descriptionValue.Len() == 0 || isPackageObject {
descriptionValue.Set(reflect.ValueOf(strings.Join(paragraphs, "\n\n")))
}
return nil
}
return fmt.Errorf("no description nor summary property")
}
func fieldProtoComments(reg *descriptor.Registry, msg *descriptor.Message, field *descriptor.Field) string {
protoPath := protoPathIndex(reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil)), "Field")
for i, f := range msg.Fields {
if f == field {
return protoComments(reg, msg.File, msg.Outers, "MessageType", int32(msg.Index), protoPath, int32(i))
}
}
return ""
}
func enumValueProtoComments(reg *descriptor.Registry, enum *descriptor.Enum) string {
protoPath := protoPathIndex(reflect.TypeOf((*pbdescriptor.EnumDescriptorProto)(nil)), "Value")
var comments []string
for idx, value := range enum.GetValue() {
name := value.GetName()
if reg.GetEnumsAsInts() {
name = strconv.Itoa(int(value.GetNumber()))
}
str := protoComments(reg, enum.File, enum.Outers, "EnumType", int32(enum.Index), protoPath, int32(idx))
if str != "" {
comments = append(comments, name+": "+str)
}
}
if len(comments) > 0 {
return "- " + strings.Join(comments, "\n - ")
}
return ""
}
func protoComments(reg *descriptor.Registry, file *descriptor.File, outers []string, typeName string, typeIndex int32, fieldPaths ...int32) string {
if file.SourceCodeInfo == nil {
fmt.Fprintln(os.Stderr, "descriptor.File should not contain nil SourceCodeInfo")
return ""
}
outerPaths := make([]int32, len(outers))
for i := range outers {
location := ""
if file.Package != nil {
location = file.GetPackage()
}
msg, err := reg.LookupMsg(location, strings.Join(outers[:i+1], "."))
if err != nil {
panic(err)
}
outerPaths[i] = int32(msg.Index)
}
for _, loc := range file.SourceCodeInfo.Location {
if !isProtoPathMatches(loc.Path, outerPaths, typeName, typeIndex, fieldPaths) {
continue
}
comments := ""
if loc.LeadingComments != nil {
comments = strings.TrimRight(*loc.LeadingComments, "\n")
comments = strings.TrimSpace(comments)
// TODO(ivucica): this is a hack to fix "// " being interpreted as "//".
// perhaps we should:
// - split by \n
// - determine if every (but first and last) line begins with " "
// - trim every line only if that is the case
// - join by \n
comments = strings.Replace(comments, "\n ", "\n", -1)
}
return comments
}
return ""
}
func goTemplateComments(comment string, data interface{}, reg *descriptor.Registry) string {
var temp bytes.Buffer
tpl, err := template.New("").Funcs(template.FuncMap{
// Allows importing documentation from a file
"import": func(name string) string {
file, err := ioutil.ReadFile(name)
if err != nil {
return err.Error()
}
// Runs template over imported file
return goTemplateComments(string(file), data, reg)
},
// Grabs title and description from a field
"fieldcomments": func(msg *descriptor.Message, field *descriptor.Field) string {
return strings.Replace(fieldProtoComments(reg, msg, field), "\n", "<br>", -1)
},
}).Parse(comment)
if err != nil {
// If there is an error parsing the templating insert the error as string in the comment
// to make it easier to debug the template error
return err.Error()
}
err = tpl.Execute(&temp, data)
if err != nil {
// If there is an error executing the templating insert the error as string in the comment
// to make it easier to debug the error
return err.Error()
}
return temp.String()
}
var messageProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "MessageType")
var nestedProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil)), "NestedType")
var packageProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "Package")
var serviceProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil)), "Service")
var methodProtoPath = protoPathIndex(reflect.TypeOf((*pbdescriptor.ServiceDescriptorProto)(nil)), "Method")
func isProtoPathMatches(paths []int32, outerPaths []int32, typeName string, typeIndex int32, fieldPaths []int32) bool {
if typeName == "Package" && typeIndex == packageProtoPath {
// path for package comments is just [2], and all the other processing
// is too complex for it.
if len(paths) == 0 || typeIndex != paths[0] {
return false
}
return true
}
if len(paths) != len(outerPaths)*2+2+len(fieldPaths) {
return false
}
if typeName == "Method" {
if paths[0] != serviceProtoPath || paths[2] != methodProtoPath {
return false
}
paths = paths[2:]
} else {
typeNameDescriptor := reflect.TypeOf((*pbdescriptor.FileDescriptorProto)(nil))
if len(outerPaths) > 0 {
if paths[0] != messageProtoPath || paths[1] != outerPaths[0] {
return false
}
paths = paths[2:]
outerPaths = outerPaths[1:]
for i, v := range outerPaths {
if paths[i*2] != nestedProtoPath || paths[i*2+1] != v {
return false
}
}
paths = paths[len(outerPaths)*2:]
if typeName == "MessageType" {
typeName = "NestedType"
}
typeNameDescriptor = reflect.TypeOf((*pbdescriptor.DescriptorProto)(nil))
}
if paths[0] != protoPathIndex(typeNameDescriptor, typeName) || paths[1] != typeIndex {
return false
}
paths = paths[2:]
}
for i, v := range fieldPaths {
if paths[i] != v {
return false
}
}
return true
}
// protoPathIndex returns a path component for google.protobuf.descriptor.SourceCode_Location.
//
// Specifically, it returns an id as generated from descriptor proto which
// can be used to determine what type the id following it in the path is.
// For example, if we are trying to locate comments related to a field named
// `Address` in a message named `Person`, the path will be:
//
// [4, a, 2, b]
//
// While `a` gets determined by the order in which the messages appear in
// the proto file, and `b` is the field index specified in the proto
// file itself, the path actually needs to specify that `a` refers to a
// message and not, say, a service; and that `b` refers to a field and not
// an option.
//
// protoPathIndex figures out the values 4 and 2 in the above example. Because
// messages are top level objects, the value of 4 comes from field id for
// `MessageType` inside `google.protobuf.descriptor.FileDescriptor` message.
// This field has a message type `google.protobuf.descriptor.DescriptorProto`.
// And inside message `DescriptorProto`, there is a field named `Field` with id
// 2.
//
// Some code generators seem to be hardcoding these values; this method instead
// interprets them from `descriptor.proto`-derived Go source as necessary.
func protoPathIndex(descriptorType reflect.Type, what string) int32 {
field, ok := descriptorType.Elem().FieldByName(what)
if !ok {
panic(fmt.Errorf("could not find protobuf descriptor type id for %s", what))
}
pbtag := field.Tag.Get("protobuf")
if pbtag == "" {
panic(fmt.Errorf("no Go tag 'protobuf' on protobuf descriptor for %s", what))
}
path, err := strconv.Atoi(strings.Split(pbtag, ",")[1])
if err != nil {
panic(fmt.Errorf("protobuf descriptor id for %s cannot be converted to a number: %s", what, err.Error()))
}
return int32(path)
}
// extractOperationOptionFromMethodDescriptor extracts the message of type
// swagger_options.Operation from a given proto method's descriptor.
func extractOperationOptionFromMethodDescriptor(meth *pbdescriptor.MethodDescriptorProto) (*swagger_options.Operation, error) {
if meth.Options == nil {
return nil, nil
}
if !proto.HasExtension(meth.Options, swagger_options.E_Openapiv2Operation) {
return nil, nil
}
ext, err := proto.GetExtension(meth.Options, swagger_options.E_Openapiv2Operation)
if err != nil {
return nil, err
}
opts, ok := ext.(*swagger_options.Operation)
if !ok {
return nil, fmt.Errorf("extension is %T; want an Operation", ext)
}
return opts, nil
}
// extractSchemaOptionFromMessageDescriptor extracts the message of type
// swagger_options.Schema from a given proto message's descriptor.
func extractSchemaOptionFromMessageDescriptor(msg *pbdescriptor.DescriptorProto) (*swagger_options.Schema, error) {
if msg.Options == nil {
return nil, nil
}
if !proto.HasExtension(msg.Options, swagger_options.E_Openapiv2Schema) {
return nil, nil
}
ext, err := proto.GetExtension(msg.Options, swagger_options.E_Openapiv2Schema)
if err != nil {
return nil, err
}
opts, ok := ext.(*swagger_options.Schema)
if !ok {
return nil, fmt.Errorf("extension is %T; want a Schema", ext)
}
return opts, nil
}
// extractSwaggerOptionFromFileDescriptor extracts the message of type
// swagger_options.Swagger from a given proto method's descriptor.
func extractSwaggerOptionFromFileDescriptor(file *pbdescriptor.FileDescriptorProto) (*swagger_options.Swagger, error) {
if file.Options == nil {
return nil, nil
}
if !proto.HasExtension(file.Options, swagger_options.E_Openapiv2Swagger) {
return nil, nil
}
ext, err := proto.GetExtension(file.Options, swagger_options.E_Openapiv2Swagger)
if err != nil {
return nil, err
}
opts, ok := ext.(*swagger_options.Swagger)
if !ok {
return nil, fmt.Errorf("extension is %T; want a Swagger object", ext)
}
return opts, nil
}
func extractJSONSchemaFromFieldDescriptor(fd *pbdescriptor.FieldDescriptorProto) (*swagger_options.JSONSchema, error) {
if fd.Options == nil {
return nil, nil
}
if !proto.HasExtension(fd.Options, swagger_options.E_Openapiv2Field) {
return nil, nil
}
ext, err := proto.GetExtension(fd.Options, swagger_options.E_Openapiv2Field)
if err != nil {
return nil, err
}
opts, ok := ext.(*swagger_options.JSONSchema)
if !ok {
return nil, fmt.Errorf("extension is %T; want a JSONSchema object", ext)
}
return opts, nil
}
func protoJSONSchemaToSwaggerSchemaCore(j *swagger_options.JSONSchema, reg *descriptor.Registry, refs refMap) schemaCore {
ret := schemaCore{}
if j.GetRef() != "" {
swaggerName, ok := fullyQualifiedNameToSwaggerName(j.GetRef(), reg)
if ok {
ret.Ref = "#/definitions/" + swaggerName
if refs != nil {
refs[j.GetRef()] = struct{}{}
}
} else {
ret.Ref += j.GetRef()
}
} else {
f, t := protoJSONSchemaTypeToFormat(j.GetType())
ret.Format = f
ret.Type = t
}
return ret
}
func updateSwaggerObjectFromJSONSchema(s *swaggerSchemaObject, j *swagger_options.JSONSchema, reg *descriptor.Registry, data interface{}) {
s.Title = j.GetTitle()
s.Description = j.GetDescription()
if reg.GetUseGoTemplate() {
s.Title = goTemplateComments(s.Title, data, reg)
s.Description = goTemplateComments(s.Description, data, reg)
}
s.ReadOnly = j.GetReadOnly()
s.MultipleOf = j.GetMultipleOf()
s.Maximum = j.GetMaximum()
s.ExclusiveMaximum = j.GetExclusiveMaximum()
s.Minimum = j.GetMinimum()
s.ExclusiveMinimum = j.GetExclusiveMinimum()
s.MaxLength = j.GetMaxLength()
s.MinLength = j.GetMinLength()
s.Pattern = j.GetPattern()
s.Default = j.GetDefault()
s.MaxItems = j.GetMaxItems()
s.MinItems = j.GetMinItems()
s.UniqueItems = j.GetUniqueItems()
s.MaxProperties = j.GetMaxProperties()
s.MinProperties = j.GetMinProperties()
s.Required = j.GetRequired()
if overrideType := j.GetType(); len(overrideType) > 0 {
s.Type = strings.ToLower(overrideType[0].String())
}
}
func swaggerSchemaFromProtoSchema(s *swagger_options.Schema, reg *descriptor.Registry, refs refMap, data interface{}) swaggerSchemaObject {
ret := swaggerSchemaObject{
ExternalDocs: protoExternalDocumentationToSwaggerExternalDocumentation(s.GetExternalDocs(), reg, data),
}
ret.schemaCore = protoJSONSchemaToSwaggerSchemaCore(s.GetJsonSchema(), reg, refs)
updateSwaggerObjectFromJSONSchema(&ret, s.GetJsonSchema(), reg, data)
if s != nil && s.Example != nil {
ret.Example = json.RawMessage(s.Example.Value)
}
return ret
}
func swaggerExamplesFromProtoExamples(in map[string]string) map[string]interface{} {
if len(in) == 0 {
return nil
}
out := make(map[string]interface{})
for mimeType, exampleStr := range in {
switch mimeType {
case "application/json":
// JSON example objects are rendered raw.
out[mimeType] = json.RawMessage(exampleStr)
default:
// All other mimetype examples are rendered as strings.
out[mimeType] = exampleStr
}
}
return out
}
func protoJSONSchemaTypeToFormat(in []swagger_options.JSONSchema_JSONSchemaSimpleTypes) (string, string) {
if len(in) == 0 {
return "", ""
}
// Can't support more than 1 type, just return the first element.
// This is due to an inconsistency in the design of the openapiv2 proto
// and that used in schemaCore. schemaCore uses the v3 definition of types,
// which only allows a single string, while the openapiv2 proto uses the OpenAPI v2
// definition, which defers to the JSON schema definition, which allows a string or an array.
// Sources:
// https://swagger.io/specification/#itemsObject
// https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.2
switch in[0] {
case swagger_options.JSONSchema_UNKNOWN, swagger_options.JSONSchema_NULL:
return "", ""
case swagger_options.JSONSchema_OBJECT:
return "object", ""
case swagger_options.JSONSchema_ARRAY:
return "array", ""
case swagger_options.JSONSchema_BOOLEAN:
return "boolean", "boolean"
case swagger_options.JSONSchema_INTEGER:
return "integer", "int32"
case swagger_options.JSONSchema_NUMBER:
return "number", "double"
case swagger_options.JSONSchema_STRING:
// NOTE: in swagger specifition, format should be empty on string type
return "string", ""
default:
// Maybe panic?
return "", ""
}
}
func protoExternalDocumentationToSwaggerExternalDocumentation(in *swagger_options.ExternalDocumentation, reg *descriptor.Registry, data interface{}) *swaggerExternalDocumentationObject {
if in == nil {
return nil
}
if reg.GetUseGoTemplate() {
in.Description = goTemplateComments(in.Description, data, reg)
}
return &swaggerExternalDocumentationObject{
Description: in.Description,
URL: in.Url,
}
}
func addCustomRefs(d swaggerDefinitionsObject, reg *descriptor.Registry, refs refMap) {
if len(refs) == 0 {
return
}
msgMap := make(messageMap)
enumMap := make(enumMap)
for ref := range refs {
swgName, swgOk := fullyQualifiedNameToSwaggerName(ref, reg)
if !swgOk {
glog.Errorf("can't resolve swagger name from CustomRef '%v'", ref)
continue
}
if _, ok := d[swgName]; ok {
// Skip already existing definitions
delete(refs, ref)
continue
}
msg, err := reg.LookupMsg("", ref)
if err == nil {
msgMap[swgName] = msg
continue
}
enum, err := reg.LookupEnum("", ref)
if err == nil {
enumMap[swgName] = enum
continue
}
// ?? Should be either enum or msg
}
renderMessagesAsDefinition(msgMap, d, reg, refs)
renderEnumerationsAsDefinition(enumMap, d, reg)
// Run again in case any new refs were added
addCustomRefs(d, reg, refs)
}
func lowerCamelCase(fieldName string, fields []*descriptor.Field, msgs []*descriptor.Message) string {
for _, oneField := range fields {
if oneField.GetName() == fieldName {
return oneField.GetJsonName()
}
}
messageNameToFieldsToJSONName := make(map[string]map[string]string, 0)
fieldNameToType := make(map[string]string, 0)
for _, msg := range msgs {
fieldNameToJSONName := make(map[string]string, 0)
for _, oneField := range msg.GetField() {
fieldNameToJSONName[oneField.GetName()] = oneField.GetJsonName()
fieldNameToType[oneField.GetName()] = oneField.GetTypeName()
}
messageNameToFieldsToJSONName[msg.GetName()] = fieldNameToJSONName
}
if strings.Contains(fieldName, ".") {
fieldNames := strings.Split(fieldName, ".")
fieldNamesWithCamelCase := make([]string, 0)
for i := 0; i < len(fieldNames)-1; i++ {
fieldNamesWithCamelCase = append(fieldNamesWithCamelCase, doCamelCase(string(fieldNames[i])))
}
prefix := strings.Join(fieldNamesWithCamelCase, ".")
reservedJSONName := getReservedJSONName(fieldName, messageNameToFieldsToJSONName, fieldNameToType)
if reservedJSONName != "" {
return prefix + "." + reservedJSONName
}
}
return doCamelCase(fieldName)
}
func doCamelCase(input string) string {
parameterString := casing.Camel(input)
builder := &strings.Builder{}
builder.WriteString(strings.ToLower(string(parameterString[0])))
builder.WriteString(parameterString[1:])
return builder.String()
}
func getReservedJSONName(fieldName string, messageNameToFieldsToJSONName map[string]map[string]string, fieldNameToType map[string]string) string {
if len(strings.Split(fieldName, ".")) == 2 {
fieldNames := strings.Split(fieldName, ".")
firstVariable := fieldNames[0]
firstType := fieldNameToType[firstVariable]
firstTypeShortNames := strings.Split(firstType, ".")
firstTypeShortName := firstTypeShortNames[len(firstTypeShortNames)-1]
return messageNameToFieldsToJSONName[firstTypeShortName][fieldNames[1]]
}
fieldNames := strings.Split(fieldName, ".")
return getReservedJSONName(strings.Join(fieldNames[1:], "."), messageNameToFieldsToJSONName, fieldNameToType)
}