1syntax = "proto3";
2
3package grpc.gateway.protoc_gen_openapiv2.options;
4
5import "google/protobuf/struct.proto";
6
7option go_package = "github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2/options";
8
9// Scheme describes the schemes supported by the OpenAPI Swagger
10// and Operation objects.
11enum Scheme {
12 UNKNOWN = 0;
13 HTTP = 1;
14 HTTPS = 2;
15 WS = 3;
16 WSS = 4;
17}
18
19// `Swagger` is a representation of OpenAPI v2 specification's Swagger object.
20//
21// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#swaggerObject
22//
23// Example:
24//
25// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
26// info: {
27// title: "Echo API";
28// version: "1.0";
29// description: "";
30// contact: {
31// name: "gRPC-Gateway project";
32// url: "https://github.com/grpc-ecosystem/grpc-gateway";
33// email: "none@example.com";
34// };
35// license: {
36// name: "BSD 3-Clause License";
37// url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/main/LICENSE";
38// };
39// };
40// schemes: HTTPS;
41// consumes: "application/json";
42// produces: "application/json";
43// };
44//
45message Swagger {
46 // Specifies the OpenAPI Specification version being used. It can be
47 // used by the OpenAPI UI and other clients to interpret the API listing. The
48 // value MUST be "2.0".
49 string swagger = 1;
50 // Provides metadata about the API. The metadata can be used by the
51 // clients if needed.
52 Info info = 2;
53 // The host (name or ip) serving the API. This MUST be the host only and does
54 // not include the scheme nor sub-paths. It MAY include a port. If the host is
55 // not included, the host serving the documentation is to be used (including
56 // the port). The host does not support path templating.
57 string host = 3;
58 // The base path on which the API is served, which is relative to the host. If
59 // it is not included, the API is served directly under the host. The value
60 // MUST start with a leading slash (/). The basePath does not support path
61 // templating.
62 // Note that using `base_path` does not change the endpoint paths that are
63 // generated in the resulting OpenAPI file. If you wish to use `base_path`
64 // with relatively generated OpenAPI paths, the `base_path` prefix must be
65 // manually removed from your `google.api.http` paths and your code changed to
66 // serve the API from the `base_path`.
67 string base_path = 4;
68 // The transfer protocol of the API. Values MUST be from the list: "http",
69 // "https", "ws", "wss". If the schemes is not included, the default scheme to
70 // be used is the one used to access the OpenAPI definition itself.
71 repeated Scheme schemes = 5;
72 // A list of MIME types the APIs can consume. This is global to all APIs but
73 // can be overridden on specific API calls. Value MUST be as described under
74 // Mime Types.
75 repeated string consumes = 6;
76 // A list of MIME types the APIs can produce. This is global to all APIs but
77 // can be overridden on specific API calls. Value MUST be as described under
78 // Mime Types.
79 repeated string produces = 7;
80 // field 8 is reserved for 'paths'.
81 reserved 8;
82 // field 9 is reserved for 'definitions', which at this time are already
83 // exposed as and customizable as proto messages.
84 reserved 9;
85 // An object to hold responses that can be used across operations. This
86 // property does not define global responses for all operations.
87 map<string, Response> responses = 10;
88 // Security scheme definitions that can be used across the specification.
89 SecurityDefinitions security_definitions = 11;
90 // A declaration of which security schemes are applied for the API as a whole.
91 // The list of values describes alternative security schemes that can be used
92 // (that is, there is a logical OR between the security requirements).
93 // Individual operations can override this definition.
94 repeated SecurityRequirement security = 12;
95 // A list of tags for API documentation control. Tags can be used for logical
96 // grouping of operations by resources or any other qualifier.
97 repeated Tag tags = 13;
98 // Additional external documentation.
99 ExternalDocumentation external_docs = 14;
100 // Custom properties that start with "x-" such as "x-foo" used to describe
101 // extra functionality that is not covered by the standard OpenAPI Specification.
102 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
103 map<string, google.protobuf.Value> extensions = 15;
104}
105
106// `Operation` is a representation of OpenAPI v2 specification's Operation object.
107//
108// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#operationObject
109//
110// Example:
111//
112// service EchoService {
113// rpc Echo(SimpleMessage) returns (SimpleMessage) {
114// option (google.api.http) = {
115// get: "/v1/example/echo/{id}"
116// };
117//
118// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = {
119// summary: "Get a message.";
120// operation_id: "getMessage";
121// tags: "echo";
122// responses: {
123// key: "200"
124// value: {
125// description: "OK";
126// }
127// }
128// };
129// }
130// }
131message Operation {
132 // A list of tags for API documentation control. Tags can be used for logical
133 // grouping of operations by resources or any other qualifier.
134 repeated string tags = 1;
135 // A short summary of what the operation does. For maximum readability in the
136 // swagger-ui, this field SHOULD be less than 120 characters.
137 string summary = 2;
138 // A verbose explanation of the operation behavior. GFM syntax can be used for
139 // rich text representation.
140 string description = 3;
141 // Additional external documentation for this operation.
142 ExternalDocumentation external_docs = 4;
143 // Unique string used to identify the operation. The id MUST be unique among
144 // all operations described in the API. Tools and libraries MAY use the
145 // operationId to uniquely identify an operation, therefore, it is recommended
146 // to follow common programming naming conventions.
147 string operation_id = 5;
148 // A list of MIME types the operation can consume. This overrides the consumes
149 // definition at the OpenAPI Object. An empty value MAY be used to clear the
150 // global definition. Value MUST be as described under Mime Types.
151 repeated string consumes = 6;
152 // A list of MIME types the operation can produce. This overrides the produces
153 // definition at the OpenAPI Object. An empty value MAY be used to clear the
154 // global definition. Value MUST be as described under Mime Types.
155 repeated string produces = 7;
156 // field 8 is reserved for 'parameters'.
157 reserved 8;
158 // The list of possible responses as they are returned from executing this
159 // operation.
160 map<string, Response> responses = 9;
161 // The transfer protocol for the operation. Values MUST be from the list:
162 // "http", "https", "ws", "wss". The value overrides the OpenAPI Object
163 // schemes definition.
164 repeated Scheme schemes = 10;
165 // Declares this operation to be deprecated. Usage of the declared operation
166 // should be refrained. Default value is false.
167 bool deprecated = 11;
168 // A declaration of which security schemes are applied for this operation. The
169 // list of values describes alternative security schemes that can be used
170 // (that is, there is a logical OR between the security requirements). This
171 // definition overrides any declared top-level security. To remove a top-level
172 // security declaration, an empty array can be used.
173 repeated SecurityRequirement security = 12;
174 // Custom properties that start with "x-" such as "x-foo" used to describe
175 // extra functionality that is not covered by the standard OpenAPI Specification.
176 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
177 map<string, google.protobuf.Value> extensions = 13;
178 // Custom parameters such as HTTP request headers.
179 // See: https://swagger.io/docs/specification/2-0/describing-parameters/
180 // and https://swagger.io/specification/v2/#parameter-object.
181 Parameters parameters = 14;
182}
183
184// `Parameters` is a representation of OpenAPI v2 specification's parameters object.
185// Note: This technically breaks compatibility with the OpenAPI 2 definition structure as we only
186// allow header parameters to be set here since we do not want users specifying custom non-header
187// parameters beyond those inferred from the Protobuf schema.
188// See: https://swagger.io/specification/v2/#parameter-object
189message Parameters {
190 // `Headers` is one or more HTTP header parameter.
191 // See: https://swagger.io/docs/specification/2-0/describing-parameters/#header-parameters
192 repeated HeaderParameter headers = 1;
193}
194
195// `HeaderParameter` a HTTP header parameter.
196// See: https://swagger.io/specification/v2/#parameter-object
197message HeaderParameter {
198 // `Type` is a a supported HTTP header type.
199 // See https://swagger.io/specification/v2/#parameterType.
200 enum Type {
201 UNKNOWN = 0;
202 STRING = 1;
203 NUMBER = 2;
204 INTEGER = 3;
205 BOOLEAN = 4;
206 }
207
208 // `Name` is the header name.
209 string name = 1;
210 // `Description` is a short description of the header.
211 string description = 2;
212 // `Type` is the type of the object. The value MUST be one of "string", "number", "integer", or "boolean". The "array" type is not supported.
213 // See: https://swagger.io/specification/v2/#parameterType.
214 Type type = 3;
215 // `Format` The extending format for the previously mentioned type.
216 string format = 4;
217 // `Required` indicates if the header is optional
218 bool required = 5;
219 // field 6 is reserved for 'items', but in OpenAPI-specific way.
220 reserved 6;
221 // field 7 is reserved `Collection Format`. Determines the format of the array if type array is used.
222 reserved 7;
223}
224
225// `Header` is a representation of OpenAPI v2 specification's Header object.
226//
227// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#headerObject
228//
229message Header {
230 // `Description` is a short description of the header.
231 string description = 1;
232 // The type of the object. The value MUST be one of "string", "number", "integer", or "boolean". The "array" type is not supported.
233 string type = 2;
234 // `Format` The extending format for the previously mentioned type.
235 string format = 3;
236 // field 4 is reserved for 'items', but in OpenAPI-specific way.
237 reserved 4;
238 // field 5 is reserved `Collection Format` Determines the format of the array if type array is used.
239 reserved 5;
240 // `Default` Declares the value of the header that the server will use if none is provided.
241 // See: https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-6.2.
242 // Unlike JSON Schema this value MUST conform to the defined type for the header.
243 string default = 6;
244 // field 7 is reserved for 'maximum'.
245 reserved 7;
246 // field 8 is reserved for 'exclusiveMaximum'.
247 reserved 8;
248 // field 9 is reserved for 'minimum'.
249 reserved 9;
250 // field 10 is reserved for 'exclusiveMinimum'.
251 reserved 10;
252 // field 11 is reserved for 'maxLength'.
253 reserved 11;
254 // field 12 is reserved for 'minLength'.
255 reserved 12;
256 // 'Pattern' See https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.2.3.
257 string pattern = 13;
258 // field 14 is reserved for 'maxItems'.
259 reserved 14;
260 // field 15 is reserved for 'minItems'.
261 reserved 15;
262 // field 16 is reserved for 'uniqueItems'.
263 reserved 16;
264 // field 17 is reserved for 'enum'.
265 reserved 17;
266 // field 18 is reserved for 'multipleOf'.
267 reserved 18;
268}
269
270// `Response` is a representation of OpenAPI v2 specification's Response object.
271//
272// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#responseObject
273//
274message Response {
275 // `Description` is a short description of the response.
276 // GFM syntax can be used for rich text representation.
277 string description = 1;
278 // `Schema` optionally defines the structure of the response.
279 // If `Schema` is not provided, it means there is no content to the response.
280 Schema schema = 2;
281 // `Headers` A list of headers that are sent with the response.
282 // `Header` name is expected to be a string in the canonical format of the MIME header key
283 // See: https://golang.org/pkg/net/textproto/#CanonicalMIMEHeaderKey
284 map<string, Header> headers = 3;
285 // `Examples` gives per-mimetype response examples.
286 // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#example-object
287 map<string, string> examples = 4;
288 // Custom properties that start with "x-" such as "x-foo" used to describe
289 // extra functionality that is not covered by the standard OpenAPI Specification.
290 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
291 map<string, google.protobuf.Value> extensions = 5;
292}
293
294// `Info` is a representation of OpenAPI v2 specification's Info object.
295//
296// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#infoObject
297//
298// Example:
299//
300// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
301// info: {
302// title: "Echo API";
303// version: "1.0";
304// description: "";
305// contact: {
306// name: "gRPC-Gateway project";
307// url: "https://github.com/grpc-ecosystem/grpc-gateway";
308// email: "none@example.com";
309// };
310// license: {
311// name: "BSD 3-Clause License";
312// url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/main/LICENSE";
313// };
314// };
315// ...
316// };
317//
318message Info {
319 // The title of the application.
320 string title = 1;
321 // A short description of the application. GFM syntax can be used for rich
322 // text representation.
323 string description = 2;
324 // The Terms of Service for the API.
325 string terms_of_service = 3;
326 // The contact information for the exposed API.
327 Contact contact = 4;
328 // The license information for the exposed API.
329 License license = 5;
330 // Provides the version of the application API (not to be confused
331 // with the specification version).
332 string version = 6;
333 // Custom properties that start with "x-" such as "x-foo" used to describe
334 // extra functionality that is not covered by the standard OpenAPI Specification.
335 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
336 map<string, google.protobuf.Value> extensions = 7;
337}
338
339// `Contact` is a representation of OpenAPI v2 specification's Contact object.
340//
341// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#contactObject
342//
343// Example:
344//
345// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
346// info: {
347// ...
348// contact: {
349// name: "gRPC-Gateway project";
350// url: "https://github.com/grpc-ecosystem/grpc-gateway";
351// email: "none@example.com";
352// };
353// ...
354// };
355// ...
356// };
357//
358message Contact {
359 // The identifying name of the contact person/organization.
360 string name = 1;
361 // The URL pointing to the contact information. MUST be in the format of a
362 // URL.
363 string url = 2;
364 // The email address of the contact person/organization. MUST be in the format
365 // of an email address.
366 string email = 3;
367}
368
369// `License` is a representation of OpenAPI v2 specification's License object.
370//
371// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#licenseObject
372//
373// Example:
374//
375// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
376// info: {
377// ...
378// license: {
379// name: "BSD 3-Clause License";
380// url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/main/LICENSE";
381// };
382// ...
383// };
384// ...
385// };
386//
387message License {
388 // The license name used for the API.
389 string name = 1;
390 // A URL to the license used for the API. MUST be in the format of a URL.
391 string url = 2;
392}
393
394// `ExternalDocumentation` is a representation of OpenAPI v2 specification's
395// ExternalDocumentation object.
396//
397// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#externalDocumentationObject
398//
399// Example:
400//
401// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_swagger) = {
402// ...
403// external_docs: {
404// description: "More about gRPC-Gateway";
405// url: "https://github.com/grpc-ecosystem/grpc-gateway";
406// }
407// ...
408// };
409//
410message ExternalDocumentation {
411 // A short description of the target documentation. GFM syntax can be used for
412 // rich text representation.
413 string description = 1;
414 // The URL for the target documentation. Value MUST be in the format
415 // of a URL.
416 string url = 2;
417}
418
419// `Schema` is a representation of OpenAPI v2 specification's Schema object.
420//
421// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject
422//
423message Schema {
424 JSONSchema json_schema = 1;
425 // Adds support for polymorphism. The discriminator is the schema property
426 // name that is used to differentiate between other schema that inherit this
427 // schema. The property name used MUST be defined at this schema and it MUST
428 // be in the required property list. When used, the value MUST be the name of
429 // this schema or any schema that inherits it.
430 string discriminator = 2;
431 // Relevant only for Schema "properties" definitions. Declares the property as
432 // "read only". This means that it MAY be sent as part of a response but MUST
433 // NOT be sent as part of the request. Properties marked as readOnly being
434 // true SHOULD NOT be in the required list of the defined schema. Default
435 // value is false.
436 bool read_only = 3;
437 // field 4 is reserved for 'xml'.
438 reserved 4;
439 // Additional external documentation for this schema.
440 ExternalDocumentation external_docs = 5;
441 // A free-form property to include an example of an instance for this schema in JSON.
442 // This is copied verbatim to the output.
443 string example = 6;
444}
445
446// `JSONSchema` represents properties from JSON Schema taken, and as used, in
447// the OpenAPI v2 spec.
448//
449// This includes changes made by OpenAPI v2.
450//
451// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject
452//
453// See also: https://cswr.github.io/JsonSchema/spec/basic_types/,
454// https://github.com/json-schema-org/json-schema-spec/blob/master/schema.json
455//
456// Example:
457//
458// message SimpleMessage {
459// option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
460// json_schema: {
461// title: "SimpleMessage"
462// description: "A simple message."
463// required: ["id"]
464// }
465// };
466//
467// // Id represents the message identifier.
468// string id = 1; [
469// (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
470// description: "The unique identifier of the simple message."
471// }];
472// }
473//
474message JSONSchema {
475 // field 1 is reserved for '$id', omitted from OpenAPI v2.
476 reserved 1;
477 // field 2 is reserved for '$schema', omitted from OpenAPI v2.
478 reserved 2;
479 // Ref is used to define an external reference to include in the message.
480 // This could be a fully qualified proto message reference, and that type must
481 // be imported into the protofile. If no message is identified, the Ref will
482 // be used verbatim in the output.
483 // For example:
484 // `ref: ".google.protobuf.Timestamp"`.
485 string ref = 3;
486 // field 4 is reserved for '$comment', omitted from OpenAPI v2.
487 reserved 4;
488 // The title of the schema.
489 string title = 5;
490 // A short description of the schema.
491 string description = 6;
492 string default = 7;
493 bool read_only = 8;
494 // A free-form property to include a JSON example of this field. This is copied
495 // verbatim to the output swagger.json. Quotes must be escaped.
496 // This property is the same for 2.0 and 3.0.0 https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/3.0.0.md#schemaObject https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#schemaObject
497 string example = 9;
498 double multiple_of = 10;
499 // Maximum represents an inclusive upper limit for a numeric instance. The
500 // value of MUST be a number,
501 double maximum = 11;
502 bool exclusive_maximum = 12;
503 // minimum represents an inclusive lower limit for a numeric instance. The
504 // value of MUST be a number,
505 double minimum = 13;
506 bool exclusive_minimum = 14;
507 uint64 max_length = 15;
508 uint64 min_length = 16;
509 string pattern = 17;
510 // field 18 is reserved for 'additionalItems', omitted from OpenAPI v2.
511 reserved 18;
512 // field 19 is reserved for 'items', but in OpenAPI-specific way.
513 // TODO(ivucica): add 'items'?
514 reserved 19;
515 uint64 max_items = 20;
516 uint64 min_items = 21;
517 bool unique_items = 22;
518 // field 23 is reserved for 'contains', omitted from OpenAPI v2.
519 reserved 23;
520 uint64 max_properties = 24;
521 uint64 min_properties = 25;
522 repeated string required = 26;
523 // field 27 is reserved for 'additionalProperties', but in OpenAPI-specific
524 // way. TODO(ivucica): add 'additionalProperties'?
525 reserved 27;
526 // field 28 is reserved for 'definitions', omitted from OpenAPI v2.
527 reserved 28;
528 // field 29 is reserved for 'properties', but in OpenAPI-specific way.
529 // TODO(ivucica): add 'additionalProperties'?
530 reserved 29;
531 // following fields are reserved, as the properties have been omitted from
532 // OpenAPI v2:
533 // patternProperties, dependencies, propertyNames, const
534 reserved 30 to 33;
535 // Items in 'array' must be unique.
536 repeated string array = 34;
537
538 enum JSONSchemaSimpleTypes {
539 UNKNOWN = 0;
540 ARRAY = 1;
541 BOOLEAN = 2;
542 INTEGER = 3;
543 NULL = 4;
544 NUMBER = 5;
545 OBJECT = 6;
546 STRING = 7;
547 }
548
549 repeated JSONSchemaSimpleTypes type = 35;
550 // `Format`
551 string format = 36;
552 // following fields are reserved, as the properties have been omitted from
553 // OpenAPI v2: contentMediaType, contentEncoding, if, then, else
554 reserved 37 to 41;
555 // field 42 is reserved for 'allOf', but in OpenAPI-specific way.
556 // TODO(ivucica): add 'allOf'?
557 reserved 42;
558 // following fields are reserved, as the properties have been omitted from
559 // OpenAPI v2:
560 // anyOf, oneOf, not
561 reserved 43 to 45;
562 // Items in `enum` must be unique https://tools.ietf.org/html/draft-fge-json-schema-validation-00#section-5.5.1
563 repeated string enum = 46;
564
565 // Additional field level properties used when generating the OpenAPI v2 file.
566 FieldConfiguration field_configuration = 1001;
567
568 // 'FieldConfiguration' provides additional field level properties used when generating the OpenAPI v2 file.
569 // These properties are not defined by OpenAPIv2, but they are used to control the generation.
570 message FieldConfiguration {
571 // Alternative parameter name when used as path parameter. If set, this will
572 // be used as the complete parameter name when this field is used as a path
573 // parameter. Use this to avoid having auto generated path parameter names
574 // for overlapping paths.
575 string path_param_name = 47;
576 }
577 // Custom properties that start with "x-" such as "x-foo" used to describe
578 // extra functionality that is not covered by the standard OpenAPI Specification.
579 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
580 map<string, google.protobuf.Value> extensions = 48;
581}
582
583// `Tag` is a representation of OpenAPI v2 specification's Tag object.
584//
585// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#tagObject
586//
587message Tag {
588 // The name of the tag. Use it to allow override of the name of a
589 // global Tag object, then use that name to reference the tag throughout the
590 // OpenAPI file.
591 string name = 1;
592 // A short description for the tag. GFM syntax can be used for rich text
593 // representation.
594 string description = 2;
595 // Additional external documentation for this tag.
596 ExternalDocumentation external_docs = 3;
597 // Custom properties that start with "x-" such as "x-foo" used to describe
598 // extra functionality that is not covered by the standard OpenAPI Specification.
599 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
600 map<string, google.protobuf.Value> extensions = 4;
601}
602
603// `SecurityDefinitions` is a representation of OpenAPI v2 specification's
604// Security Definitions object.
605//
606// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securityDefinitionsObject
607//
608// A declaration of the security schemes available to be used in the
609// specification. This does not enforce the security schemes on the operations
610// and only serves to provide the relevant details for each scheme.
611message SecurityDefinitions {
612 // A single security scheme definition, mapping a "name" to the scheme it
613 // defines.
614 map<string, SecurityScheme> security = 1;
615}
616
617// `SecurityScheme` is a representation of OpenAPI v2 specification's
618// Security Scheme object.
619//
620// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securitySchemeObject
621//
622// Allows the definition of a security scheme that can be used by the
623// operations. Supported schemes are basic authentication, an API key (either as
624// a header or as a query parameter) and OAuth2's common flows (implicit,
625// password, application and access code).
626message SecurityScheme {
627 // The type of the security scheme. Valid values are "basic",
628 // "apiKey" or "oauth2".
629 enum Type {
630 TYPE_INVALID = 0;
631 TYPE_BASIC = 1;
632 TYPE_API_KEY = 2;
633 TYPE_OAUTH2 = 3;
634 }
635
636 // The location of the API key. Valid values are "query" or "header".
637 enum In {
638 IN_INVALID = 0;
639 IN_QUERY = 1;
640 IN_HEADER = 2;
641 }
642
643 // The flow used by the OAuth2 security scheme. Valid values are
644 // "implicit", "password", "application" or "accessCode".
645 enum Flow {
646 FLOW_INVALID = 0;
647 FLOW_IMPLICIT = 1;
648 FLOW_PASSWORD = 2;
649 FLOW_APPLICATION = 3;
650 FLOW_ACCESS_CODE = 4;
651 }
652
653 // The type of the security scheme. Valid values are "basic",
654 // "apiKey" or "oauth2".
655 Type type = 1;
656 // A short description for security scheme.
657 string description = 2;
658 // The name of the header or query parameter to be used.
659 // Valid for apiKey.
660 string name = 3;
661 // The location of the API key. Valid values are "query" or
662 // "header".
663 // Valid for apiKey.
664 In in = 4;
665 // The flow used by the OAuth2 security scheme. Valid values are
666 // "implicit", "password", "application" or "accessCode".
667 // Valid for oauth2.
668 Flow flow = 5;
669 // The authorization URL to be used for this flow. This SHOULD be in
670 // the form of a URL.
671 // Valid for oauth2/implicit and oauth2/accessCode.
672 string authorization_url = 6;
673 // The token URL to be used for this flow. This SHOULD be in the
674 // form of a URL.
675 // Valid for oauth2/password, oauth2/application and oauth2/accessCode.
676 string token_url = 7;
677 // The available scopes for the OAuth2 security scheme.
678 // Valid for oauth2.
679 Scopes scopes = 8;
680 // Custom properties that start with "x-" such as "x-foo" used to describe
681 // extra functionality that is not covered by the standard OpenAPI Specification.
682 // See: https://swagger.io/docs/specification/2-0/swagger-extensions/
683 map<string, google.protobuf.Value> extensions = 9;
684}
685
686// `SecurityRequirement` is a representation of OpenAPI v2 specification's
687// Security Requirement object.
688//
689// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#securityRequirementObject
690//
691// Lists the required security schemes to execute this operation. The object can
692// have multiple security schemes declared in it which are all required (that
693// is, there is a logical AND between the schemes).
694//
695// The name used for each property MUST correspond to a security scheme
696// declared in the Security Definitions.
697message SecurityRequirement {
698 // If the security scheme is of type "oauth2", then the value is a list of
699 // scope names required for the execution. For other security scheme types,
700 // the array MUST be empty.
701 message SecurityRequirementValue {
702 repeated string scope = 1;
703 }
704 // Each name must correspond to a security scheme which is declared in
705 // the Security Definitions. If the security scheme is of type "oauth2",
706 // then the value is a list of scope names required for the execution.
707 // For other security scheme types, the array MUST be empty.
708 map<string, SecurityRequirementValue> security_requirement = 1;
709}
710
711// `Scopes` is a representation of OpenAPI v2 specification's Scopes object.
712//
713// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#scopesObject
714//
715// Lists the available scopes for an OAuth2 security scheme.
716message Scopes {
717 // Maps between a name of a scope to a short description of it (as the value
718 // of the property).
719 map<string, string> scope = 1;
720}
View as plain text