types.go

Documentation: github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger/genswagger

     1  package genswagger
     2  
     3  import (
     4  	"bytes"
     5  	"encoding/json"
     6  	"fmt"
     7  
     8  	"github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway/descriptor"
     9  )
    10  
    11  type param struct {
    12  	*descriptor.File
    13  	reg *descriptor.Registry
    14  }
    15  
    16  type binding struct {
    17  	*descriptor.Binding
    18  }
    19  
    20  // http://swagger.io/specification/#infoObject
    21  type swaggerInfoObject struct {
    22  	Title          string `json:"title"`
    23  	Description    string `json:"description,omitempty"`
    24  	TermsOfService string `json:"termsOfService,omitempty"`
    25  	Version        string `json:"version"`
    26  
    27  	Contact *swaggerContactObject `json:"contact,omitempty"`
    28  	License *swaggerLicenseObject `json:"license,omitempty"`
    29  
    30  	extensions []extension
    31  }
    32  
    33  // http://swagger.io/specification/#contactObject
    34  type swaggerContactObject struct {
    35  	Name  string `json:"name,omitempty"`
    36  	URL   string `json:"url,omitempty"`
    37  	Email string `json:"email,omitempty"`
    38  }
    39  
    40  // http://swagger.io/specification/#licenseObject
    41  type swaggerLicenseObject struct {
    42  	Name string `json:"name,omitempty"`
    43  	URL  string `json:"url,omitempty"`
    44  }
    45  
    46  // http://swagger.io/specification/#externalDocumentationObject
    47  type swaggerExternalDocumentationObject struct {
    48  	Description string `json:"description,omitempty"`
    49  	URL         string `json:"url,omitempty"`
    50  }
    51  
    52  type extension struct {
    53  	key   string
    54  	value json.RawMessage
    55  }
    56  
    57  // http://swagger.io/specification/#swaggerObject
    58  type swaggerObject struct {
    59  	Swagger             string                              `json:"swagger"`
    60  	Info                swaggerInfoObject                   `json:"info"`
    61  	Host                string                              `json:"host,omitempty"`
    62  	BasePath            string                              `json:"basePath,omitempty"`
    63  	Schemes             []string                            `json:"schemes,omitempty"`
    64  	Consumes            []string                            `json:"consumes"`
    65  	Produces            []string                            `json:"produces"`
    66  	Paths               swaggerPathsObject                  `json:"paths"`
    67  	Definitions         swaggerDefinitionsObject            `json:"definitions"`
    68  	SecurityDefinitions swaggerSecurityDefinitionsObject    `json:"securityDefinitions,omitempty"`
    69  	Security            []swaggerSecurityRequirementObject  `json:"security,omitempty"`
    70  	ExternalDocs        *swaggerExternalDocumentationObject `json:"externalDocs,omitempty"`
    71  
    72  	extensions []extension
    73  }
    74  
    75  // http://swagger.io/specification/#securityDefinitionsObject
    76  type swaggerSecurityDefinitionsObject map[string]swaggerSecuritySchemeObject
    77  
    78  // http://swagger.io/specification/#securitySchemeObject
    79  type swaggerSecuritySchemeObject struct {
    80  	Type             string              `json:"type"`
    81  	Description      string              `json:"description,omitempty"`
    82  	Name             string              `json:"name,omitempty"`
    83  	In               string              `json:"in,omitempty"`
    84  	Flow             string              `json:"flow,omitempty"`
    85  	AuthorizationURL string              `json:"authorizationUrl,omitempty"`
    86  	TokenURL         string              `json:"tokenUrl,omitempty"`
    87  	Scopes           swaggerScopesObject `json:"scopes,omitempty"`
    88  
    89  	extensions []extension
    90  }
    91  
    92  // http://swagger.io/specification/#scopesObject
    93  type swaggerScopesObject map[string]string
    94  
    95  // http://swagger.io/specification/#securityRequirementObject
    96  type swaggerSecurityRequirementObject map[string][]string
    97  
    98  // http://swagger.io/specification/#pathsObject
    99  type swaggerPathsObject map[string]swaggerPathItemObject
   100  
   101  // http://swagger.io/specification/#pathItemObject
   102  type swaggerPathItemObject struct {
   103  	Get    *swaggerOperationObject `json:"get,omitempty"`
   104  	Delete *swaggerOperationObject `json:"delete,omitempty"`
   105  	Post   *swaggerOperationObject `json:"post,omitempty"`
   106  	Put    *swaggerOperationObject `json:"put,omitempty"`
   107  	Patch  *swaggerOperationObject `json:"patch,omitempty"`
   108  }
   109  
   110  // http://swagger.io/specification/#operationObject
   111  type swaggerOperationObject struct {
   112  	Summary     string                  `json:"summary,omitempty"`
   113  	Description string                  `json:"description,omitempty"`
   114  	OperationID string                  `json:"operationId"`
   115  	Responses   swaggerResponsesObject  `json:"responses"`
   116  	Parameters  swaggerParametersObject `json:"parameters,omitempty"`
   117  	Tags        []string                `json:"tags,omitempty"`
   118  	Deprecated  bool                    `json:"deprecated,omitempty"`
   119  	Produces    []string                `json:"produces,omitempty"`
   120  
   121  	Security     *[]swaggerSecurityRequirementObject `json:"security,omitempty"`
   122  	ExternalDocs *swaggerExternalDocumentationObject `json:"externalDocs,omitempty"`
   123  
   124  	extensions []extension
   125  }
   126  
   127  type swaggerParametersObject []swaggerParameterObject
   128  
   129  // http://swagger.io/specification/#parameterObject
   130  type swaggerParameterObject struct {
   131  	Name             string              `json:"name"`
   132  	Description      string              `json:"description,omitempty"`
   133  	In               string              `json:"in,omitempty"`
   134  	Required         bool                `json:"required"`
   135  	Type             string              `json:"type,omitempty"`
   136  	Format           string              `json:"format,omitempty"`
   137  	Items            *swaggerItemsObject `json:"items,omitempty"`
   138  	Enum             []string            `json:"enum,omitempty"`
   139  	CollectionFormat string              `json:"collectionFormat,omitempty"`
   140  	Default          string              `json:"default,omitempty"`
   141  	MinItems         *int                `json:"minItems,omitempty"`
   142  
   143  	// Or you can explicitly refer to another type. If this is defined all
   144  	// other fields should be empty
   145  	Schema *swaggerSchemaObject `json:"schema,omitempty"`
   146  }
   147  
   148  // core part of schema, which is common to itemsObject and schemaObject.
   149  // http://swagger.io/specification/#itemsObject
   150  type schemaCore struct {
   151  	Type    string          `json:"type,omitempty"`
   152  	Format  string          `json:"format,omitempty"`
   153  	Ref     string          `json:"$ref,omitempty"`
   154  	Example json.RawMessage `json:"example,omitempty"`
   155  
   156  	Items *swaggerItemsObject `json:"items,omitempty"`
   157  
   158  	// If the item is an enumeration include a list of all the *NAMES* of the
   159  	// enum values.  I'm not sure how well this will work but assuming all enums
   160  	// start from 0 index it will be great. I don't think that is a good assumption.
   161  	Enum    []string `json:"enum,omitempty"`
   162  	Default string   `json:"default,omitempty"`
   163  }
   164  
   165  func (s *schemaCore) setRefFromFQN(ref string, reg *descriptor.Registry) error {
   166  	name, ok := fullyQualifiedNameToSwaggerName(ref, reg)
   167  	if !ok {
   168  		return fmt.Errorf("setRefFromFQN: can't resolve swagger name from '%v'", ref)
   169  	}
   170  	s.Ref = fmt.Sprintf("#/definitions/%s", name)
   171  	return nil
   172  }
   173  
   174  type swaggerItemsObject schemaCore
   175  
   176  // http://swagger.io/specification/#responsesObject
   177  type swaggerResponsesObject map[string]swaggerResponseObject
   178  
   179  // http://swagger.io/specification/#responseObject
   180  type swaggerResponseObject struct {
   181  	Description string                 `json:"description"`
   182  	Schema      swaggerSchemaObject    `json:"schema"`
   183  	Examples    map[string]interface{} `json:"examples,omitempty"`
   184  	Headers     swaggerHeadersObject   `json:"headers,omitempty"`
   185  
   186  	extensions []extension
   187  }
   188  
   189  type swaggerHeadersObject map[string]swaggerHeaderObject
   190  
   191  // http://swagger.io/specification/#headerObject
   192  type swaggerHeaderObject struct {
   193  	Description string          `json:"description,omitempty"`
   194  	Type        string          `json:"type,omitempty"`
   195  	Format      string          `json:"format,omitempty"`
   196  	Default     json.RawMessage `json:"default,omitempty"`
   197  	Pattern     string          `json:"pattern,omitempty"`
   198  }
   199  
   200  type keyVal struct {
   201  	Key   string
   202  	Value interface{}
   203  }
   204  
   205  type swaggerSchemaObjectProperties []keyVal
   206  
   207  func (op swaggerSchemaObjectProperties) MarshalJSON() ([]byte, error) {
   208  	var buf bytes.Buffer
   209  	buf.WriteString("{")
   210  	for i, kv := range op {
   211  		if i != 0 {
   212  			buf.WriteString(",")
   213  		}
   214  		key, err := json.Marshal(kv.Key)
   215  		if err != nil {
   216  			return nil, err
   217  		}
   218  		buf.Write(key)
   219  		buf.WriteString(":")
   220  		val, err := json.Marshal(kv.Value)
   221  		if err != nil {
   222  			return nil, err
   223  		}
   224  		buf.Write(val)
   225  	}
   226  
   227  	buf.WriteString("}")
   228  	return buf.Bytes(), nil
   229  }
   230  
   231  // http://swagger.io/specification/#schemaObject
   232  type swaggerSchemaObject struct {
   233  	schemaCore
   234  	// Properties can be recursively defined
   235  	Properties           *swaggerSchemaObjectProperties `json:"properties,omitempty"`
   236  	AdditionalProperties *swaggerSchemaObject           `json:"additionalProperties,omitempty"`
   237  
   238  	Description string `json:"description,omitempty"`
   239  	Title       string `json:"title,omitempty"`
   240  
   241  	ExternalDocs *swaggerExternalDocumentationObject `json:"externalDocs,omitempty"`
   242  
   243  	ReadOnly         bool     `json:"readOnly,omitempty"`
   244  	MultipleOf       float64  `json:"multipleOf,omitempty"`
   245  	Maximum          float64  `json:"maximum,omitempty"`
   246  	ExclusiveMaximum bool     `json:"exclusiveMaximum,omitempty"`
   247  	Minimum          float64  `json:"minimum,omitempty"`
   248  	ExclusiveMinimum bool     `json:"exclusiveMinimum,omitempty"`
   249  	MaxLength        uint64   `json:"maxLength,omitempty"`
   250  	MinLength        uint64   `json:"minLength,omitempty"`
   251  	Pattern          string   `json:"pattern,omitempty"`
   252  	MaxItems         uint64   `json:"maxItems,omitempty"`
   253  	MinItems         uint64   `json:"minItems,omitempty"`
   254  	UniqueItems      bool     `json:"uniqueItems,omitempty"`
   255  	MaxProperties    uint64   `json:"maxProperties,omitempty"`
   256  	MinProperties    uint64   `json:"minProperties,omitempty"`
   257  	Required         []string `json:"required,omitempty"`
   258  }
   259  
   260  // http://swagger.io/specification/#referenceObject
   261  type swaggerReferenceObject struct {
   262  	Ref string `json:"$ref"`
   263  }
   264  
   265  // http://swagger.io/specification/#definitionsObject
   266  type swaggerDefinitionsObject map[string]swaggerSchemaObject
   267  
   268  // Internal type mapping from FQMN to descriptor.Message. Used as a set by the
   269  // findServiceMessages function.
   270  type messageMap map[string]*descriptor.Message
   271  
   272  // Internal type mapping from FQEN to descriptor.Enum. Used as a set by the
   273  // findServiceMessages function.
   274  type enumMap map[string]*descriptor.Enum
   275  
   276  // Internal type to store used references.
   277  type refMap map[string]struct{}
   278
View as plain text