1syntax = "proto3";  2  3// Package grpc.gateway.protoc_gen_openapiv3.options defines the minimal set of  4// OpenAPI 3.1.0 override messages consumed by protoc-gen-openapiv3.  5package grpc.gateway.protoc_gen_openapiv3.options;  6  7import "google/protobuf/struct.proto";  8  9option go_package = "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv3/options"; 10 11// Document is a file-level override applied to the top of the generated 12// OpenAPI document. Only non-empty sub-fields replace the defaults the 13// generator would otherwise synthesize from the proto file name. 14// 15// Spec: https://spec.openapis.org/oas/v3.1.0#openapi-object 16message Document { 17  // Provides metadata about the API. The metadata MAY be used by tooling as 18  // required. 19  Info info = 1; 20  // An array of Server Objects, which provide connectivity information to a 21  // target server. If the servers property is not provided, or is an empty 22  // array, the default value would be a Server Object with a url value of /. 23  repeated Server servers = 2; 24  // Additional external documentation. 25  ExternalDocs external_docs = 3; 26  // A list of tags used by the document with additional metadata. Tags 27  // declared here are merged with the tags derived from proto services: an 28  // entry here whose name matches a service's tag replaces the default, 29  // and entries with new names are appended. This is the only way to 30  // attach a description (or external docs) to a tag referenced by a 31  // method-level `openapiv3_operation.tags` override, since those tags 32  // would otherwise appear in the document with no metadata. 33  repeated Tag tags = 4; 34  // Custom specification extensions rendered at the root of the OpenAPI 35  // document. Keys MUST start with "x-". 36  // 37  // See: https://spec.openapis.org/oas/v3.1.0#specification-extensions 38  map<string, google.protobuf.Value> extensions = 5; 39} 40 41// Info mirrors the fields of the OpenAPI 3.1.0 Info object that users most 42// often want to set from proto. 43// 44// Spec: https://spec.openapis.org/oas/v3.1.0#info-object 45message Info { 46  // The title of the API. 47  string title = 1; 48  // A short summary of the API. 49  string summary = 2; 50  // A description of the API. CommonMark syntax MAY be used for rich text 51  // representation. 52  string description = 3; 53  // A URL to the Terms of Service for the API. This MUST be in the form of a 54  // URL. 55  string terms_of_service = 4; 56  // The contact information for the exposed API. 57  Contact contact = 5; 58  // The license information for the exposed API. 59  License license = 6; 60  // The version of the OpenAPI document (which is distinct from the OpenAPI 61  // Specification version or the API implementation version). 62  string version = 7; 63  // Custom specification extensions rendered on the Info object. Keys MUST 64  // start with "x-". 65  // 66  // See: https://spec.openapis.org/oas/v3.1.0#specification-extensions 67  map<string, google.protobuf.Value> extensions = 8; 68} 69 70// Contact information for the exposed API. 71// 72// Spec: https://spec.openapis.org/oas/v3.1.0#contact-object 73message Contact { 74  // The identifying name of the contact person/organization. 75  string name = 1; 76  // The URL pointing to the contact information. This MUST be in the form of 77  // a URL. 78  string url = 2; 79  // The email address of the contact person/organization. This MUST be in the 80  // form of an email address. 81  string email = 3; 82} 83 84// License information for the exposed API. `identifier` and `url` are 85// mutually exclusive in the OpenAPI 3.1.0 spec, so they are modeled as a 86// oneof: setting one clears the other. 87// 88// Spec: https://spec.openapis.org/oas/v3.1.0#license-object 89message License { 90  // The license name used for the API. 91  string name = 1; 92  // Source identifying the license. Either an SPDX expression or a URL, 93  // mutually exclusive per the OpenAPI 3.1.0 spec. 94  oneof source { 95    // An SPDX expression for the API. 96    string identifier = 2; 97    // A URL to the license used for the API. This MUST be in the form of a 98    // URL. 99    string url = 3;100  }101}102103// Server represents an API server.104//105// Spec: https://spec.openapis.org/oas/v3.1.0#server-object106message Server {107  // A URL to the target host. This URL supports Server Variables and MAY be108  // relative, to indicate that the host location is relative to the location109  // where the OpenAPI document is being served.110  string url = 1;111  // An optional string describing the host designated by the URL. CommonMark112  // syntax MAY be used for rich text representation.113  string description = 2;114}115116// Operation is a method-level override applied to the generated Operation117// object. Non-empty fields replace values the generator would otherwise118// derive from proto comments or defaults.119//120// Spec: https://spec.openapis.org/oas/v3.1.0#operation-object121message Operation {122  // A list of tags for API documentation control. Tags can be used for123  // logical grouping of operations by resources or any other qualifier.124  repeated string tags = 1;125  // A short summary of what the operation does.126  string summary = 2;127  // A verbose explanation of the operation behavior. CommonMark syntax MAY128  // be used for rich text representation.129  string description = 3;130  // Additional external documentation for this operation.131  ExternalDocs external_docs = 4;132  // Unique string used to identify the operation. The id MUST be unique among133  // all operations described in the API.134  string operation_id = 5;135  // Declares this operation to be deprecated. Consumers SHOULD refrain from136  // usage of the declared operation. Default value is false. Setting this to137  // false does not un-deprecate a method that is marked deprecated in proto138  // (`option deprecated = true` on the method, service, or file).139  bool deprecated = 6;140  // An alternative `servers` array to service this operation. If a `servers`141  // array is specified at the Path Item Object or OpenAPI Object level, it142  // will be overridden by this value.143  repeated Server servers = 7;144  // Custom specification extensions rendered on the Operation object. Keys145  // MUST start with "x-".146  //147  // See: https://spec.openapis.org/oas/v3.1.0#specification-extensions148  map<string, google.protobuf.Value> extensions = 8;149}150151// Schema is a message- or field-level override applied to the generated152// JSON Schema. Non-empty fields replace values the generator would153// otherwise derive from proto comments or the proto type.154//155// Both `openapiv3_schema` (on MessageOptions) and `openapiv3_field` (on156// FieldOptions) use this message.157//158// Spec: https://spec.openapis.org/oas/v3.1.0#schema-object159// Underlying dialect: https://json-schema.org/draft/2020-12/json-schema-core160message Schema {161  // A preferably short string describing the purpose of the instance162  // described by the schema.163  string title = 1;164  // A string providing explanation about the purpose of the instance165  // described by the schema.166  string description = 2;167  // Declares this schema to be deprecated. Consumers SHOULD refrain from168  // usage of the declared schema. Default value is false. Setting this to169  // false does not un-deprecate a schema that is marked deprecated in proto170  // (`option deprecated = true` on the message, field, or file).171  bool deprecated = 3;172  // Custom specification extensions rendered on the Schema object. Keys173  // MUST start with "x-". Setting this on a field-level annotation forces174  // a schema body (like `title`), so a $ref-typed field carrying extensions175  // is wrapped in `allOf`.176  //177  // See: https://spec.openapis.org/oas/v3.1.0#specification-extensions178  map<string, google.protobuf.Value> extensions = 4;179}180181// ExternalDocs is a link to external documentation.182//183// Spec: https://spec.openapis.org/oas/v3.1.0#external-documentation-object184message ExternalDocs {185  // A description of the target documentation. CommonMark syntax MAY be used186  // for rich text representation.187  string description = 1;188  // The URL for the target documentation. This MUST be in the form of a URL.189  string url = 2;190}191192// Tag adds metadata to a single tag that is used by the Operation Object. It193// is not mandatory to have a Tag Object per tag defined in the Operation194// Object instances.195//196// Spec: https://spec.openapis.org/oas/v3.1.0#tag-object197message Tag {198  // The name of the tag.199  string name = 1;200  // A description for the tag. CommonMark syntax MAY be used for rich text201  // representation.202  string description = 2;203  // Additional external documentation for this tag.204  ExternalDocs external_docs = 3;205  // Custom specification extensions rendered on the Tag object. Keys MUST206  // start with "x-".207  //208  // See: https://spec.openapis.org/oas/v3.1.0#specification-extensions209  map<string, google.protobuf.Value> extensions = 4;210}