diff --git a/protoc-gen-swagger/options/openapiv2.pb.go b/protoc-gen-swagger/options/openapiv2.pb.go index 8ea807582e2..c15e2d14845 100644 --- a/protoc-gen-swagger/options/openapiv2.pb.go +++ b/protoc-gen-swagger/options/openapiv2.pb.go @@ -99,7 +99,7 @@ func (JSONSchema_JSONSchemaSimpleTypes) EnumDescriptor() ([]byte, []int) { return fileDescriptor_ba35ad8af024fb48, []int{8, 0} } -// Required. The type of the security scheme. Valid values are "basic", +// The type of the security scheme. Valid values are "basic", // "apiKey" or "oauth2". type SecurityScheme_Type int32 @@ -132,7 +132,7 @@ func (SecurityScheme_Type) EnumDescriptor() ([]byte, []int) { return fileDescriptor_ba35ad8af024fb48, []int{11, 0} } -// Required. The location of the API key. Valid values are "query" or "header". +// The location of the API key. Valid values are "query" or "header". type SecurityScheme_In int32 const ( @@ -161,7 +161,7 @@ func (SecurityScheme_In) EnumDescriptor() ([]byte, []int) { return fileDescriptor_ba35ad8af024fb48, []int{11, 1} } -// Required. The flow used by the OAuth2 security scheme. Valid values are +// The flow used by the OAuth2 security scheme. Valid values are // "implicit", "password", "application" or "accessCode". type SecurityScheme_Flow int32 @@ -201,24 +201,52 @@ func (SecurityScheme_Flow) EnumDescriptor() ([]byte, []int) { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#swaggerObject // -// TODO(ivucica): document fields type Swagger struct { + // Specifies the Swagger Specification version being used. It can be + // used by the Swagger UI and other clients to interpret the API listing. The + // value MUST be "2.0". Swagger string `protobuf:"bytes,1,opt,name=swagger,proto3" json:"swagger,omitempty"` - Info *Info `protobuf:"bytes,2,opt,name=info,proto3" json:"info,omitempty"` - Host string `protobuf:"bytes,3,opt,name=host,proto3" json:"host,omitempty"` - // `base_path` is the common prefix path used on all API endpoints (ie. /api, /v1, etc.). By adding this, - // it allows you to remove this portion from the path endpoints in your Swagger file making them easier - // to read. Note that using `base_path` does not change the endpoint paths that are generated in the resulting - // Swagger file. If you wish to use `base_path` with relatively generated Swagger paths, the - // `base_path` prefix must be manually removed from your `google.api.http` paths and your code changed to + // Provides metadata about the API. The metadata can be used by the + // clients if needed. + Info *Info `protobuf:"bytes,2,opt,name=info,proto3" json:"info,omitempty"` + // The host (name or ip) serving the API. This MUST be the host only and does + // not include the scheme nor sub-paths. It MAY include a port. If the host is + // not included, the host serving the documentation is to be used (including + // the port). The host does not support path templating. + Host string `protobuf:"bytes,3,opt,name=host,proto3" json:"host,omitempty"` + // The base path on which the API is served, which is relative to the host. If + // it is not included, the API is served directly under the host. The value + // MUST start with a leading slash (/). The basePath does not support path + // templating. + // Note that using `base_path` does not change the endpoint paths that are + // generated in the resulting Swagger file. If you wish to use `base_path` + // with relatively generated Swagger paths, the `base_path` prefix must be + // manually removed from your `google.api.http` paths and your code changed to // serve the API from the `base_path`. - BasePath string `protobuf:"bytes,4,opt,name=base_path,json=basePath,proto3" json:"base_path,omitempty"` - Schemes []Swagger_SwaggerScheme `protobuf:"varint,5,rep,packed,name=schemes,proto3,enum=grpc.gateway.protoc_gen_swagger.options.Swagger_SwaggerScheme" json:"schemes,omitempty"` - Consumes []string `protobuf:"bytes,6,rep,name=consumes,proto3" json:"consumes,omitempty"` - Produces []string `protobuf:"bytes,7,rep,name=produces,proto3" json:"produces,omitempty"` - Responses map[string]*Response `protobuf:"bytes,10,rep,name=responses,proto3" json:"responses,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` - SecurityDefinitions *SecurityDefinitions `protobuf:"bytes,11,opt,name=security_definitions,json=securityDefinitions,proto3" json:"security_definitions,omitempty"` - Security []*SecurityRequirement `protobuf:"bytes,12,rep,name=security,proto3" json:"security,omitempty"` + BasePath string `protobuf:"bytes,4,opt,name=base_path,json=basePath,proto3" json:"base_path,omitempty"` + // The transfer protocol of the API. Values MUST be from the list: "http", + // "https", "ws", "wss". If the schemes is not included, the default scheme to + // be used is the one used to access the Swagger definition itself. + Schemes []Swagger_SwaggerScheme `protobuf:"varint,5,rep,packed,name=schemes,proto3,enum=grpc.gateway.protoc_gen_swagger.options.Swagger_SwaggerScheme" json:"schemes,omitempty"` + // A list of MIME types the APIs can consume. This is global to all APIs but + // can be overridden on specific API calls. Value MUST be as described under + // Mime Types. + Consumes []string `protobuf:"bytes,6,rep,name=consumes,proto3" json:"consumes,omitempty"` + // A list of MIME types the APIs can produce. This is global to all APIs but + // can be overridden on specific API calls. Value MUST be as described under + // Mime Types. + Produces []string `protobuf:"bytes,7,rep,name=produces,proto3" json:"produces,omitempty"` + // An object to hold responses that can be used across operations. This + // property does not define global responses for all operations. + Responses map[string]*Response `protobuf:"bytes,10,rep,name=responses,proto3" json:"responses,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` + // Security scheme definitions that can be used across the specification. + SecurityDefinitions *SecurityDefinitions `protobuf:"bytes,11,opt,name=security_definitions,json=securityDefinitions,proto3" json:"security_definitions,omitempty"` + // A declaration of which security schemes are applied for the API as a whole. + // The list of values describes alternative security schemes that can be used + // (that is, there is a logical OR between the security requirements). + // Individual operations can override this definition. + Security []*SecurityRequirement `protobuf:"bytes,12,rep,name=security,proto3" json:"security,omitempty"` + // Additional external documentation. ExternalDocs *ExternalDocumentation `protobuf:"bytes,14,opt,name=external_docs,json=externalDocs,proto3" json:"external_docs,omitempty"` Extensions map[string]*_struct.Value `protobuf:"bytes,15,rep,name=extensions,proto3" json:"extensions,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -339,18 +367,46 @@ func (m *Swagger) GetExtensions() map[string]*_struct.Value { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#operationObject // -// TODO(ivucica): document fields type Operation struct { - Tags []string `protobuf:"bytes,1,rep,name=tags,proto3" json:"tags,omitempty"` - Summary string `protobuf:"bytes,2,opt,name=summary,proto3" json:"summary,omitempty"` - Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"` - ExternalDocs *ExternalDocumentation `protobuf:"bytes,4,opt,name=external_docs,json=externalDocs,proto3" json:"external_docs,omitempty"` - OperationId string `protobuf:"bytes,5,opt,name=operation_id,json=operationId,proto3" json:"operation_id,omitempty"` - Consumes []string `protobuf:"bytes,6,rep,name=consumes,proto3" json:"consumes,omitempty"` - Produces []string `protobuf:"bytes,7,rep,name=produces,proto3" json:"produces,omitempty"` - Responses map[string]*Response `protobuf:"bytes,9,rep,name=responses,proto3" json:"responses,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` - Schemes []string `protobuf:"bytes,10,rep,name=schemes,proto3" json:"schemes,omitempty"` - Deprecated bool `protobuf:"varint,11,opt,name=deprecated,proto3" json:"deprecated,omitempty"` + // A list of tags for API documentation control. Tags can be used for logical + // grouping of operations by resources or any other qualifier. + Tags []string `protobuf:"bytes,1,rep,name=tags,proto3" json:"tags,omitempty"` + // A short summary of what the operation does. For maximum readability in the + // swagger-ui, this field SHOULD be less than 120 characters. + Summary string `protobuf:"bytes,2,opt,name=summary,proto3" json:"summary,omitempty"` + // A verbose explanation of the operation behavior. GFM syntax can be used for + // rich text representation. + Description string `protobuf:"bytes,3,opt,name=description,proto3" json:"description,omitempty"` + // Additional external documentation for this operation. + ExternalDocs *ExternalDocumentation `protobuf:"bytes,4,opt,name=external_docs,json=externalDocs,proto3" json:"external_docs,omitempty"` + // Unique string used to identify the operation. The id MUST be unique among + // all operations described in the API. Tools and libraries MAY use the + // operationId to uniquely identify an operation, therefore, it is recommended + // to follow common programming naming conventions. + OperationId string `protobuf:"bytes,5,opt,name=operation_id,json=operationId,proto3" json:"operation_id,omitempty"` + // A list of MIME types the operation can consume. This overrides the consumes + // definition at the Swagger Object. An empty value MAY be used to clear the + // global definition. Value MUST be as described under Mime Types. + Consumes []string `protobuf:"bytes,6,rep,name=consumes,proto3" json:"consumes,omitempty"` + // A list of MIME types the operation can produce. This overrides the produces + // definition at the Swagger Object. An empty value MAY be used to clear the + // global definition. Value MUST be as described under Mime Types. + Produces []string `protobuf:"bytes,7,rep,name=produces,proto3" json:"produces,omitempty"` + // The list of possible responses as they are returned from executing this + // operation. + Responses map[string]*Response `protobuf:"bytes,9,rep,name=responses,proto3" json:"responses,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` + // The transfer protocol for the operation. Values MUST be from the list: + // "http", "https", "ws", "wss". The value overrides the Swagger Object + // schemes definition. + Schemes []string `protobuf:"bytes,10,rep,name=schemes,proto3" json:"schemes,omitempty"` + // Declares this operation to be deprecated. Usage of the declared operation + // should be refrained. Default value is false. + Deprecated bool `protobuf:"varint,11,opt,name=deprecated,proto3" json:"deprecated,omitempty"` + // A declaration of which security schemes are applied for this operation. The + // list of values describes alternative security schemes that can be used + // (that is, there is a logical OR between the security requirements). This + // definition overrides any declared top-level security. To remove a top-level + // security declaration, an empty array can be used. Security []*SecurityRequirement `protobuf:"bytes,12,rep,name=security,proto3" json:"security,omitempty"` Extensions map[string]*_struct.Value `protobuf:"bytes,13,rep,name=extensions,proto3" json:"extensions,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -544,13 +600,20 @@ func (m *Response) GetExtensions() map[string]*_struct.Value { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#infoObject // -// TODO(ivucica): document fields type Info struct { - Title string `protobuf:"bytes,1,opt,name=title,proto3" json:"title,omitempty"` - Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` - TermsOfService string `protobuf:"bytes,3,opt,name=terms_of_service,json=termsOfService,proto3" json:"terms_of_service,omitempty"` - Contact *Contact `protobuf:"bytes,4,opt,name=contact,proto3" json:"contact,omitempty"` - License *License `protobuf:"bytes,5,opt,name=license,proto3" json:"license,omitempty"` + // The title of the application. + Title string `protobuf:"bytes,1,opt,name=title,proto3" json:"title,omitempty"` + // A short description of the application. GFM syntax can be used for rich + // text representation. + Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` + // The Terms of Service for the API. + TermsOfService string `protobuf:"bytes,3,opt,name=terms_of_service,json=termsOfService,proto3" json:"terms_of_service,omitempty"` + // The contact information for the exposed API. + Contact *Contact `protobuf:"bytes,4,opt,name=contact,proto3" json:"contact,omitempty"` + // The license information for the exposed API. + License *License `protobuf:"bytes,5,opt,name=license,proto3" json:"license,omitempty"` + // Provides the version of the application API (not to be confused + // with the specification version). Version string `protobuf:"bytes,6,opt,name=version,proto3" json:"version,omitempty"` Extensions map[string]*_struct.Value `protobuf:"bytes,7,rep,name=extensions,proto3" json:"extensions,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` XXX_NoUnkeyedLiteral struct{} `json:"-"` @@ -636,10 +699,14 @@ func (m *Info) GetExtensions() map[string]*_struct.Value { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#contactObject // -// TODO(ivucica): document fields type Contact struct { - Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` - Url string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"` + // The identifying name of the contact person/organization. + Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` + // The URL pointing to the contact information. MUST be in the format of a + // URL. + Url string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"` + // The email address of the contact person/organization. MUST be in the format + // of an email address. Email string `protobuf:"bytes,3,opt,name=email,proto3" json:"email,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -697,9 +764,9 @@ func (m *Contact) GetEmail() string { // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#licenseObject // type License struct { - // Required. The license name used for the API. + // The license name used for the API. Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"` - // A URL to the license used for the API. + // A URL to the license used for the API. MUST be in the format of a URL. Url string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -750,9 +817,12 @@ func (m *License) GetUrl() string { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#externalDocumentationObject // -// TODO(ivucica): document fields type ExternalDocumentation struct { - Description string `protobuf:"bytes,1,opt,name=description,proto3" json:"description,omitempty"` + // A short description of the target documentation. GFM syntax can be used for + // rich text representation. + Description string `protobuf:"bytes,1,opt,name=description,proto3" json:"description,omitempty"` + // The URL for the target documentation. Value MUST be in the format + // of a URL. Url string `protobuf:"bytes,2,opt,name=url,proto3" json:"url,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -802,16 +872,27 @@ func (m *ExternalDocumentation) GetUrl() string { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject // -// TODO(ivucica): document fields type Schema struct { - JsonSchema *JSONSchema `protobuf:"bytes,1,opt,name=json_schema,json=jsonSchema,proto3" json:"json_schema,omitempty"` - Discriminator string `protobuf:"bytes,2,opt,name=discriminator,proto3" json:"discriminator,omitempty"` - ReadOnly bool `protobuf:"varint,3,opt,name=read_only,json=readOnly,proto3" json:"read_only,omitempty"` - ExternalDocs *ExternalDocumentation `protobuf:"bytes,5,opt,name=external_docs,json=externalDocs,proto3" json:"external_docs,omitempty"` - Example *any.Any `protobuf:"bytes,6,opt,name=example,proto3" json:"example,omitempty"` - XXX_NoUnkeyedLiteral struct{} `json:"-"` - XXX_unrecognized []byte `json:"-"` - XXX_sizecache int32 `json:"-"` + JsonSchema *JSONSchema `protobuf:"bytes,1,opt,name=json_schema,json=jsonSchema,proto3" json:"json_schema,omitempty"` + // Adds support for polymorphism. The discriminator is the schema property + // name that is used to differentiate between other schema that inherit this + // schema. The property name used MUST be defined at this schema and it MUST + // be in the required property list. When used, the value MUST be the name of + // this schema or any schema that inherits it. + Discriminator string `protobuf:"bytes,2,opt,name=discriminator,proto3" json:"discriminator,omitempty"` + // Relevant only for Schema "properties" definitions. Declares the property as + // "read only". This means that it MAY be sent as part of a response but MUST + // NOT be sent as part of the request. Properties marked as readOnly being + // true SHOULD NOT be in the required list of the defined schema. Default + // value is false. + ReadOnly bool `protobuf:"varint,3,opt,name=read_only,json=readOnly,proto3" json:"read_only,omitempty"` + // Additional external documentation for this schema. + ExternalDocs *ExternalDocumentation `protobuf:"bytes,5,opt,name=external_docs,json=externalDocs,proto3" json:"external_docs,omitempty"` + // A free-form property to include an example of an instance for this schema. + Example *any.Any `protobuf:"bytes,6,opt,name=example,proto3" json:"example,omitempty"` + XXX_NoUnkeyedLiteral struct{} `json:"-"` + XXX_unrecognized []byte `json:"-"` + XXX_sizecache int32 `json:"-"` } func (m *Schema) Reset() { *m = Schema{} } @@ -887,19 +968,25 @@ func (m *Schema) GetExample() *any.Any { // TODO(ivucica): document fields type JSONSchema struct { // Ref is used to define an external reference to include in the message. - // This could be a fully qualified proto message reference, and that type must be imported - // into the protofile. If no message is identified, the Ref will be used verbatim in - // the output. + // This could be a fully qualified proto message reference, and that type must + // be imported into the protofile. If no message is identified, the Ref will + // be used verbatim in the output. // For example: // `ref: ".google.protobuf.Timestamp"`. - Ref string `protobuf:"bytes,3,opt,name=ref,proto3" json:"ref,omitempty"` - Title string `protobuf:"bytes,5,opt,name=title,proto3" json:"title,omitempty"` - Description string `protobuf:"bytes,6,opt,name=description,proto3" json:"description,omitempty"` - Default string `protobuf:"bytes,7,opt,name=default,proto3" json:"default,omitempty"` - ReadOnly bool `protobuf:"varint,8,opt,name=read_only,json=readOnly,proto3" json:"read_only,omitempty"` - MultipleOf float64 `protobuf:"fixed64,10,opt,name=multiple_of,json=multipleOf,proto3" json:"multiple_of,omitempty"` - Maximum float64 `protobuf:"fixed64,11,opt,name=maximum,proto3" json:"maximum,omitempty"` - ExclusiveMaximum bool `protobuf:"varint,12,opt,name=exclusive_maximum,json=exclusiveMaximum,proto3" json:"exclusive_maximum,omitempty"` + Ref string `protobuf:"bytes,3,opt,name=ref,proto3" json:"ref,omitempty"` + // The title of the schema. + Title string `protobuf:"bytes,5,opt,name=title,proto3" json:"title,omitempty"` + // A short description of the schema. + Description string `protobuf:"bytes,6,opt,name=description,proto3" json:"description,omitempty"` + Default string `protobuf:"bytes,7,opt,name=default,proto3" json:"default,omitempty"` + ReadOnly bool `protobuf:"varint,8,opt,name=read_only,json=readOnly,proto3" json:"read_only,omitempty"` + MultipleOf float64 `protobuf:"fixed64,10,opt,name=multiple_of,json=multipleOf,proto3" json:"multiple_of,omitempty"` + // Maximum represents an inclusive upper limit for a numeric instance. The + // value of MUST be a number, + Maximum float64 `protobuf:"fixed64,11,opt,name=maximum,proto3" json:"maximum,omitempty"` + ExclusiveMaximum bool `protobuf:"varint,12,opt,name=exclusive_maximum,json=exclusiveMaximum,proto3" json:"exclusive_maximum,omitempty"` + // minimum represents an inclusive lower limit for a numeric instance. The + // value of MUST be a number, Minimum float64 `protobuf:"fixed64,13,opt,name=minimum,proto3" json:"minimum,omitempty"` ExclusiveMinimum bool `protobuf:"varint,14,opt,name=exclusive_minimum,json=exclusiveMinimum,proto3" json:"exclusive_minimum,omitempty"` MaxLength uint64 `protobuf:"varint,15,opt,name=max_length,json=maxLength,proto3" json:"max_length,omitempty"` @@ -1095,11 +1182,11 @@ func (m *JSONSchema) GetType() []JSONSchema_JSONSchemaSimpleTypes { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#tagObject // -// TODO(ivucica): document fields type Tag struct { - // TODO(ivucica): Description should be extracted from comments on the proto - // service object. - Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` + // A short description for the tag. GFM syntax can be used for rich text + // representation. + Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` + // Additional external documentation for this tag. ExternalDocs *ExternalDocumentation `protobuf:"bytes,3,opt,name=external_docs,json=externalDocs,proto3" json:"external_docs,omitempty"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1154,7 +1241,8 @@ func (m *Tag) GetExternalDocs() *ExternalDocumentation { // specification. This does not enforce the security schemes on the operations // and only serves to provide the relevant details for each scheme. type SecurityDefinitions struct { - // A single security scheme definition, mapping a "name" to the scheme it defines. + // A single security scheme definition, mapping a "name" to the scheme it + // defines. Security map[string]*SecurityScheme `protobuf:"bytes,1,rep,name=security,proto3" json:"security,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` XXX_NoUnkeyedLiteral struct{} `json:"-"` XXX_unrecognized []byte `json:"-"` @@ -1203,36 +1291,31 @@ func (m *SecurityDefinitions) GetSecurity() map[string]*SecurityScheme { // a header or as a query parameter) and OAuth2's common flows (implicit, // password, application and access code). type SecurityScheme struct { - // Required. The type of the security scheme. Valid values are "basic", + // The type of the security scheme. Valid values are "basic", // "apiKey" or "oauth2". Type SecurityScheme_Type `protobuf:"varint,1,opt,name=type,proto3,enum=grpc.gateway.protoc_gen_swagger.options.SecurityScheme_Type" json:"type,omitempty"` // A short description for security scheme. Description string `protobuf:"bytes,2,opt,name=description,proto3" json:"description,omitempty"` - // Required. The name of the header or query parameter to be used. - // + // The name of the header or query parameter to be used. // Valid for apiKey. Name string `protobuf:"bytes,3,opt,name=name,proto3" json:"name,omitempty"` - // Required. The location of the API key. Valid values are "query" or "header". - // + // The location of the API key. Valid values are "query" or + // "header". // Valid for apiKey. In SecurityScheme_In `protobuf:"varint,4,opt,name=in,proto3,enum=grpc.gateway.protoc_gen_swagger.options.SecurityScheme_In" json:"in,omitempty"` - // Required. The flow used by the OAuth2 security scheme. Valid values are + // The flow used by the OAuth2 security scheme. Valid values are // "implicit", "password", "application" or "accessCode". - // // Valid for oauth2. Flow SecurityScheme_Flow `protobuf:"varint,5,opt,name=flow,proto3,enum=grpc.gateway.protoc_gen_swagger.options.SecurityScheme_Flow" json:"flow,omitempty"` - // Required. The authorization URL to be used for this flow. This SHOULD be in + // The authorization URL to be used for this flow. This SHOULD be in // the form of a URL. - // // Valid for oauth2/implicit and oauth2/accessCode. AuthorizationUrl string `protobuf:"bytes,6,opt,name=authorization_url,json=authorizationUrl,proto3" json:"authorization_url,omitempty"` - // Required. The token URL to be used for this flow. This SHOULD be in the + // The token URL to be used for this flow. This SHOULD be in the // form of a URL. - // // Valid for oauth2/password, oauth2/application and oauth2/accessCode. TokenUrl string `protobuf:"bytes,7,opt,name=token_url,json=tokenUrl,proto3" json:"token_url,omitempty"` - // Required. The available scopes for the OAuth2 security scheme. - // + // The available scopes for the OAuth2 security scheme. // Valid for oauth2. Scopes *Scopes `protobuf:"bytes,8,opt,name=scopes,proto3" json:"scopes,omitempty"` Extensions map[string]*_struct.Value `protobuf:"bytes,9,rep,name=extensions,proto3" json:"extensions,omitempty" protobuf_key:"bytes,1,opt,name=key,proto3" protobuf_val:"bytes,2,opt,name=value,proto3"` diff --git a/protoc-gen-swagger/options/openapiv2.proto b/protoc-gen-swagger/options/openapiv2.proto index 3dcac4d99ff..f3c05f492fb 100644 --- a/protoc-gen-swagger/options/openapiv2.proto +++ b/protoc-gen-swagger/options/openapiv2.proto @@ -11,16 +11,27 @@ import "google/protobuf/struct.proto"; // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#swaggerObject // -// TODO(ivucica): document fields message Swagger { + // Specifies the Swagger Specification version being used. It can be + // used by the Swagger UI and other clients to interpret the API listing. The + // value MUST be "2.0". string swagger = 1; + // Provides metadata about the API. The metadata can be used by the + // clients if needed. Info info = 2; + // The host (name or ip) serving the API. This MUST be the host only and does + // not include the scheme nor sub-paths. It MAY include a port. If the host is + // not included, the host serving the documentation is to be used (including + // the port). The host does not support path templating. string host = 3; - // `base_path` is the common prefix path used on all API endpoints (ie. /api, /v1, etc.). By adding this, - // it allows you to remove this portion from the path endpoints in your Swagger file making them easier - // to read. Note that using `base_path` does not change the endpoint paths that are generated in the resulting - // Swagger file. If you wish to use `base_path` with relatively generated Swagger paths, the - // `base_path` prefix must be manually removed from your `google.api.http` paths and your code changed to + // The base path on which the API is served, which is relative to the host. If + // it is not included, the API is served directly under the host. The value + // MUST start with a leading slash (/). The basePath does not support path + // templating. + // Note that using `base_path` does not change the endpoint paths that are + // generated in the resulting Swagger file. If you wish to use `base_path` + // with relatively generated Swagger paths, the `base_path` prefix must be + // manually removed from your `google.api.http` paths and your code changed to // serve the API from the `base_path`. string base_path = 4; enum SwaggerScheme { @@ -30,21 +41,38 @@ message Swagger { WS = 3; WSS = 4; } + // The transfer protocol of the API. Values MUST be from the list: "http", + // "https", "ws", "wss". If the schemes is not included, the default scheme to + // be used is the one used to access the Swagger definition itself. repeated SwaggerScheme schemes = 5; + // A list of MIME types the APIs can consume. This is global to all APIs but + // can be overridden on specific API calls. Value MUST be as described under + // Mime Types. repeated string consumes = 6; + // A list of MIME types the APIs can produce. This is global to all APIs but + // can be overridden on specific API calls. Value MUST be as described under + // Mime Types. repeated string produces = 7; // field 8 is reserved for 'paths'. reserved 8; // field 9 is reserved for 'definitions', which at this time are already // exposed as and customizable as proto messages. reserved 9; + // An object to hold responses that can be used across operations. This + // property does not define global responses for all operations. map responses = 10; + // Security scheme definitions that can be used across the specification. SecurityDefinitions security_definitions = 11; + // A declaration of which security schemes are applied for the API as a whole. + // The list of values describes alternative security schemes that can be used + // (that is, there is a logical OR between the security requirements). + // Individual operations can override this definition. repeated SecurityRequirement security = 12; // field 13 is reserved for 'tags', which are supposed to be exposed as and // customizable as proto services. TODO(ivucica): add processing of proto // service objects into OpenAPI v2 Tag objects. reserved 13; + // Additional external documentation. ExternalDocumentation external_docs = 14; map extensions = 15; } @@ -53,20 +81,48 @@ message Swagger { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#operationObject // -// TODO(ivucica): document fields message Operation { + // A list of tags for API documentation control. Tags can be used for logical + // grouping of operations by resources or any other qualifier. repeated string tags = 1; + // A short summary of what the operation does. For maximum readability in the + // swagger-ui, this field SHOULD be less than 120 characters. string summary = 2; + // A verbose explanation of the operation behavior. GFM syntax can be used for + // rich text representation. string description = 3; + // Additional external documentation for this operation. ExternalDocumentation external_docs = 4; + // Unique string used to identify the operation. The id MUST be unique among + // all operations described in the API. Tools and libraries MAY use the + // operationId to uniquely identify an operation, therefore, it is recommended + // to follow common programming naming conventions. string operation_id = 5; + // A list of MIME types the operation can consume. This overrides the consumes + // definition at the Swagger Object. An empty value MAY be used to clear the + // global definition. Value MUST be as described under Mime Types. repeated string consumes = 6; + // A list of MIME types the operation can produce. This overrides the produces + // definition at the Swagger Object. An empty value MAY be used to clear the + // global definition. Value MUST be as described under Mime Types. repeated string produces = 7; // field 8 is reserved for 'parameters'. reserved 8; + // The list of possible responses as they are returned from executing this + // operation. map responses = 9; + // The transfer protocol for the operation. Values MUST be from the list: + // "http", "https", "ws", "wss". The value overrides the Swagger Object + // schemes definition. repeated string schemes = 10; + // Declares this operation to be deprecated. Usage of the declared operation + // should be refrained. Default value is false. bool deprecated = 11; + // A declaration of which security schemes are applied for this operation. The + // list of values describes alternative security schemes that can be used + // (that is, there is a logical OR between the security requirements). This + // definition overrides any declared top-level security. To remove a top-level + // security declaration, an empty array can be used. repeated SecurityRequirement security = 12; map extensions = 13; } @@ -94,13 +150,20 @@ message Response { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#infoObject // -// TODO(ivucica): document fields message Info { + // The title of the application. string title = 1; + // A short description of the application. GFM syntax can be used for rich + // text representation. string description = 2; + // The Terms of Service for the API. string terms_of_service = 3; + // The contact information for the exposed API. Contact contact = 4; + // The license information for the exposed API. License license = 5; + // Provides the version of the application API (not to be confused + // with the specification version). string version = 6; map extensions = 7; } @@ -109,10 +172,14 @@ message Info { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#contactObject // -// TODO(ivucica): document fields message Contact { + // The identifying name of the contact person/organization. string name = 1; + // The URL pointing to the contact information. MUST be in the format of a + // URL. string url = 2; + // The email address of the contact person/organization. MUST be in the format + // of an email address. string email = 3; } @@ -121,9 +188,9 @@ message Contact { // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#licenseObject // message License { - // Required. The license name used for the API. + // The license name used for the API. string name = 1; - // A URL to the license used for the API. + // A URL to the license used for the API. MUST be in the format of a URL. string url = 2; } @@ -132,9 +199,12 @@ message License { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#externalDocumentationObject // -// TODO(ivucica): document fields message ExternalDocumentation { + // A short description of the target documentation. GFM syntax can be used for + // rich text representation. string description = 1; + // The URL for the target documentation. Value MUST be in the format + // of a URL. string url = 2; } @@ -142,14 +212,25 @@ message ExternalDocumentation { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject // -// TODO(ivucica): document fields message Schema { JSONSchema json_schema = 1; + // Adds support for polymorphism. The discriminator is the schema property + // name that is used to differentiate between other schema that inherit this + // schema. The property name used MUST be defined at this schema and it MUST + // be in the required property list. When used, the value MUST be the name of + // this schema or any schema that inherits it. string discriminator = 2; + // Relevant only for Schema "properties" definitions. Declares the property as + // "read only". This means that it MAY be sent as part of a response but MUST + // NOT be sent as part of the request. Properties marked as readOnly being + // true SHOULD NOT be in the required list of the defined schema. Default + // value is false. bool read_only = 3; // field 4 is reserved for 'xml'. reserved 4; + // Additional external documentation for this schema. ExternalDocumentation external_docs = 5; + // A free-form property to include an example of an instance for this schema. google.protobuf.Any example = 6; } @@ -170,23 +251,30 @@ message JSONSchema { // field 2 is reserved for '$schema', omitted from OpenAPI v2. reserved 2; // Ref is used to define an external reference to include in the message. - // This could be a fully qualified proto message reference, and that type must be imported - // into the protofile. If no message is identified, the Ref will be used verbatim in - // the output. + // This could be a fully qualified proto message reference, and that type must + // be imported into the protofile. If no message is identified, the Ref will + // be used verbatim in the output. // For example: // `ref: ".google.protobuf.Timestamp"`. string ref = 3; // field 4 is reserved for '$comment', omitted from OpenAPI v2. reserved 4; + // The title of the schema. string title = 5; + // A short description of the schema. string description = 6; string default = 7; bool read_only = 8; - // field 9 is reserved for 'examples', which is omitted from OpenAPI v2 in favor of 'example' field. + // field 9 is reserved for 'examples', which is omitted from OpenAPI v2 in + // favor of 'example' field. reserved 9; double multiple_of = 10; + // Maximum represents an inclusive upper limit for a numeric instance. The + // value of MUST be a number, double maximum = 11; bool exclusive_maximum = 12; + // minimum represents an inclusive lower limit for a numeric instance. The + // value of MUST be a number, double minimum = 13; bool exclusive_minimum = 14; uint64 max_length = 15; @@ -194,7 +282,8 @@ message JSONSchema { string pattern = 17; // field 18 is reserved for 'additionalItems', omitted from OpenAPI v2. reserved 18; - // field 19 is reserved for 'items', but in OpenAPI-specific way. TODO(ivucica): add 'items'? + // field 19 is reserved for 'items', but in OpenAPI-specific way. + // TODO(ivucica): add 'items'? reserved 19; uint64 max_items = 20; uint64 min_items = 21; @@ -204,13 +293,16 @@ message JSONSchema { uint64 max_properties = 24; uint64 min_properties = 25; repeated string required = 26; - // field 27 is reserved for 'additionalProperties', but in OpenAPI-specific way. TODO(ivucica): add 'additionalProperties'? + // field 27 is reserved for 'additionalProperties', but in OpenAPI-specific + // way. TODO(ivucica): add 'additionalProperties'? reserved 27; // field 28 is reserved for 'definitions', omitted from OpenAPI v2. reserved 28; - // field 29 is reserved for 'properties', but in OpenAPI-specific way. TODO(ivucica): add 'additionalProperties'? + // field 29 is reserved for 'properties', but in OpenAPI-specific way. + // TODO(ivucica): add 'additionalProperties'? reserved 29; - // following fields are reserved, as the properties have been omitted from OpenAPI v2: + // following fields are reserved, as the properties have been omitted from + // OpenAPI v2: // patternProperties, dependencies, propertyNames, const reserved 30 to 33; // Items in 'array' must be unique. @@ -228,12 +320,14 @@ message JSONSchema { } repeated JSONSchemaSimpleTypes type = 35; - // following fields are reserved, as the properties have been omitted from OpenAPI v2: - // format, contentMediaType, contentEncoding, if, then, else + // following fields are reserved, as the properties have been omitted from + // OpenAPI v2: format, contentMediaType, contentEncoding, if, then, else reserved 36 to 41; - // field 42 is reserved for 'allOf', but in OpenAPI-specific way. TODO(ivucica): add 'allOf'? + // field 42 is reserved for 'allOf', but in OpenAPI-specific way. + // TODO(ivucica): add 'allOf'? reserved 42; - // following fields are reserved, as the properties have been omitted from OpenAPI v2: + // following fields are reserved, as the properties have been omitted from + // OpenAPI v2: // anyOf, oneOf, not reserved 43 to 45; } @@ -242,7 +336,6 @@ message JSONSchema { // // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#tagObject // -// TODO(ivucica): document fields message Tag { // field 1 is reserved for 'name'. In our generator, this is (to be) extracted // from the name of proto service, and thus not exposed to the user, as @@ -253,9 +346,10 @@ message Tag { // global Tag object, then use that name to reference the tag throughout the // Swagger file. reserved 1; - // TODO(ivucica): Description should be extracted from comments on the proto - // service object. + // A short description for the tag. GFM syntax can be used for rich text + // representation. string description = 2; + // Additional external documentation for this tag. ExternalDocumentation external_docs = 3; } @@ -268,7 +362,8 @@ message Tag { // specification. This does not enforce the security schemes on the operations // and only serves to provide the relevant details for each scheme. message SecurityDefinitions { - // A single security scheme definition, mapping a "name" to the scheme it defines. + // A single security scheme definition, mapping a "name" to the scheme it + // defines. map security = 1; } @@ -282,7 +377,7 @@ message SecurityDefinitions { // a header or as a query parameter) and OAuth2's common flows (implicit, // password, application and access code). message SecurityScheme { - // Required. The type of the security scheme. Valid values are "basic", + // The type of the security scheme. Valid values are "basic", // "apiKey" or "oauth2". enum Type { TYPE_INVALID = 0; @@ -291,14 +386,14 @@ message SecurityScheme { TYPE_OAUTH2 = 3; } - // Required. The location of the API key. Valid values are "query" or "header". + // The location of the API key. Valid values are "query" or "header". enum In { IN_INVALID = 0; IN_QUERY = 1; IN_HEADER = 2; } - // Required. The flow used by the OAuth2 security scheme. Valid values are + // The flow used by the OAuth2 security scheme. Valid values are // "implicit", "password", "application" or "accessCode". enum Flow { FLOW_INVALID = 0; @@ -308,36 +403,31 @@ message SecurityScheme { FLOW_ACCESS_CODE = 4; } - // Required. The type of the security scheme. Valid values are "basic", + // The type of the security scheme. Valid values are "basic", // "apiKey" or "oauth2". Type type = 1; // A short description for security scheme. string description = 2; - // Required. The name of the header or query parameter to be used. - // + // The name of the header or query parameter to be used. // Valid for apiKey. string name = 3; - // Required. The location of the API key. Valid values are "query" or "header". - // + // The location of the API key. Valid values are "query" or + // "header". // Valid for apiKey. In in = 4; - // Required. The flow used by the OAuth2 security scheme. Valid values are + // The flow used by the OAuth2 security scheme. Valid values are // "implicit", "password", "application" or "accessCode". - // // Valid for oauth2. Flow flow = 5; - // Required. The authorization URL to be used for this flow. This SHOULD be in + // The authorization URL to be used for this flow. This SHOULD be in // the form of a URL. - // // Valid for oauth2/implicit and oauth2/accessCode. string authorization_url = 6; - // Required. The token URL to be used for this flow. This SHOULD be in the + // The token URL to be used for this flow. This SHOULD be in the // form of a URL. - // // Valid for oauth2/password, oauth2/application and oauth2/accessCode. string token_url = 7; - // Required. The available scopes for the OAuth2 security scheme. - // + // The available scopes for the OAuth2 security scheme. // Valid for oauth2. Scopes scopes = 8; map extensions = 9;