@@ -26,15 +26,15 @@ enum Scheme {
2626// info: {
2727// title: "Echo API";
2828// version: "1.0";
29- // description: ";
29+ // description: "" ;
3030// contact: {
3131// name: "gRPC-Gateway project";
3232// url: "https://github.com/grpc-ecosystem/grpc-gateway";
33333434// };
3535// license: {
3636// name: "BSD 3-Clause License";
37- // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master /LICENSE.txt ";
37+ // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/main /LICENSE";
3838// };
3939// };
4040// schemes: HTTPS;
@@ -92,12 +92,14 @@ message Swagger {
9292 // (that is, there is a logical OR between the security requirements).
9393 // Individual operations can override this definition.
9494 repeated SecurityRequirement security = 12 ;
95- // field 13 is reserved for 'tags', which are supposed to be exposed as and
96- // customizable as proto services. TODO(ivucica): add processing of proto
97- // service objects into OpenAPI v2 Tag objects.
98- reserved 13 ;
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 ;
9998 // Additional external documentation.
10099 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/
101103 map <string , google.protobuf.Value > extensions = 15 ;
102104}
103105
@@ -169,7 +171,55 @@ message Operation {
169171 // definition overrides any declared top-level security. To remove a top-level
170172 // security declaration, an empty array can be used.
171173 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/
172177 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
189+ message 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
197+ message 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 ;
173223}
174224
175225// `Header` is a representation of OpenAPI v2 specification's Header object.
@@ -235,6 +285,9 @@ message Response {
235285 // `Examples` gives per-mimetype response examples.
236286 // See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#example-object
237287 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/
238291 map <string , google.protobuf.Value > extensions = 5 ;
239292}
240293
@@ -248,15 +301,15 @@ message Response {
248301// info: {
249302// title: "Echo API";
250303// version: "1.0";
251- // description: ";
304+ // description: "" ;
252305// contact: {
253306// name: "gRPC-Gateway project";
254307// url: "https://github.com/grpc-ecosystem/grpc-gateway";
255308256309// };
257310// license: {
258311// name: "BSD 3-Clause License";
259- // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master /LICENSE.txt ";
312+ // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/main /LICENSE";
260313// };
261314// };
262315// ...
@@ -277,6 +330,9 @@ message Info {
277330 // Provides the version of the application API (not to be confused
278331 // with the specification version).
279332 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/
280336 map <string , google.protobuf.Value > extensions = 7 ;
281337}
282338
@@ -321,7 +377,7 @@ message Contact {
321377// ...
322378// license: {
323379// name: "BSD 3-Clause License";
324- // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/master /LICENSE.txt ";
380+ // url: "https://github.com/grpc-ecosystem/grpc-gateway/blob/main /LICENSE";
325381// };
326382// ...
327383// };
@@ -518,6 +574,9 @@ message JSONSchema {
518574 // for overlapping paths.
519575 string path_param_name = 47 ;
520576 }
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/
521580 map <string , google.protobuf.Value > extensions = 48 ;
522581}
523582
@@ -526,20 +585,19 @@ message JSONSchema {
526585// See: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#tagObject
527586//
528587message Tag {
529- // field 1 is reserved for 'name'. In our generator, this is (to be) extracted
530- // from the name of proto service, and thus not exposed to the user, as
531- // changing tag object's name would break the link to the references to the
532- // tag in individual operation specifications.
533- //
534- // TODO(ivucica): Add 'name' property. Use it to allow override of the name of
588+ // The name of the tag. Use it to allow override of the name of a
535589 // global Tag object, then use that name to reference the tag throughout the
536590 // OpenAPI file.
537- reserved 1 ;
591+ string name = 1 ;
538592 // A short description for the tag. GFM syntax can be used for rich text
539593 // representation.
540594 string description = 2 ;
541595 // Additional external documentation for this tag.
542596 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 ;
543601}
544602
545603// `SecurityDefinitions` is a representation of OpenAPI v2 specification's
@@ -619,6 +677,9 @@ message SecurityScheme {
619677 // The available scopes for the OAuth2 security scheme.
620678 // Valid for oauth2.
621679 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/
622683 map <string , google.protobuf.Value > extensions = 9 ;
623684}
624685
0 commit comments