Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

protoc-gen-swagger: Add ability to specify custom response objects #663

Merged
merged 2 commits into from
Jun 20, 2018
Merged

protoc-gen-swagger: Add ability to specify custom response objects #663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
15cae3f
Examples: Consistently use tabs in a_bit_of_everything
johanbrandhorst May 31, 2018
9ed7b67
protoc-gen-swagger: Add ability to specify custom response objects
johanbrandhorst May 31, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions examples/clients/abe/examplepb_a_bit_of_everything.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ import (
"time"
)

// Intentionaly complicated message type to cover many features of Protobuf.
type ExamplepbABitOfEverything struct {

SingleNested ABitOfEverythingNested `json:"single_nested,omitempty"`
Expand Down
356 changes: 184 additions & 172 deletions examples/proto/examplepb/a_bit_of_everything.pb.go
View file
Open in desktop

Large diffs are not rendered by default.

268 changes: 159 additions & 109 deletions examples/proto/examplepb/a_bit_of_everything.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,96 +11,128 @@ import "google/protobuf/timestamp.proto";
import "protoc-gen-swagger/options/annotations.proto";

option (grpc.gateway.protoc_gen_swagger.options.openapiv2_swagger) = {
info: {
title: "A Bit of Everything";
version: "1.0";
contact: {
name: "gRPC-Gateway project";
url: "https://github.com/grpc-ecosystem/grpc-gateway";
email: "[email protected]";
};
};
// Overwriting host entry breaks tests, so this is not done here.
external_docs: {
url: "https://github.com/grpc-ecosystem/grpc-gateway";
description: "More about gRPC-Gateway";
}
schemes: HTTP;
schemes: HTTPS;
schemes: WSS;
consumes: "application/json";
consumes: "application/x-foo-mime";
produces: "application/json";
produces: "application/x-foo-mime";
security_definitions: {
security: {
key: "BasicAuth";
value: {
type: TYPE_BASIC;
}
}
security: {
key: "ApiKeyAuth";
value: {
type: TYPE_API_KEY;
in: IN_HEADER;
name: "X-API-Key";
}
}
security: {
key: "OAuth2";
value: {
type: TYPE_OAUTH2;
flow: FLOW_ACCESS_CODE;
authorization_url: "https://example.com/oauth/authorize";
token_url: "https://example.com/oauth/token";
scopes: {
scope: {
key: "read";
value: "Grants read access";
}
scope: {
key: "write";
value: "Grants write access";
}
scope: {
key: "admin";
value: "Grants read and write access to administrative information";
}
info: {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Out of curiosity, why did you change everything to be tabs? Can you run this through a modern version of clang-format?

Copy link
Collaborator Author

@johanbrandhorst johanbrandhorst Jun 1, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Everything except for the examples added by @ivucica was already tabs, so I just made it consistent as it was driving me mad. I could format this (and the other protofiles) with prototool format 1 if you like, but I haven't touched the others.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Sorry about this.)

title: "A Bit of Everything";
version: "1.0";
contact: {
name: "gRPC-Gateway project";
url: "https://github.com/grpc-ecosystem/grpc-gateway";
email: "[email protected]";
};
};
// Overwriting host entry breaks tests, so this is not done here.
external_docs: {
url: "https://github.com/grpc-ecosystem/grpc-gateway";
description: "More about gRPC-Gateway";
}
schemes: HTTP;
schemes: HTTPS;
schemes: WSS;
consumes: "application/json";
consumes: "application/x-foo-mime";
produces: "application/json";
produces: "application/x-foo-mime";
security_definitions: {
security: {
key: "BasicAuth";
value: {
type: TYPE_BASIC;
}
}
security: {
key: "ApiKeyAuth";
value: {
type: TYPE_API_KEY;
in: IN_HEADER;
name: "X-API-Key";
}
}
security: {
key: "OAuth2";
value: {
type: TYPE_OAUTH2;
flow: FLOW_ACCESS_CODE;
authorization_url: "https://example.com/oauth/authorize";
token_url: "https://example.com/oauth/token";
scopes: {
scope: {
key: "read";
value: "Grants read access";
}
scope: {
key: "write";
value: "Grants write access";
}
scope: {
key: "admin";
value: "Grants read and write access to administrative information";
}
}
}
}
}
security: {
security_requirement: {
key: "BasicAuth";
value: {};
}
security_requirement: {
key: "ApiKeyAuth";
value: {};
}
}
security: {
security_requirement: {
key: "OAuth2";
value: {
scope: "read";
scope: "write";
}
}
security_requirement: {
key: "ApiKeyAuth";
value: {};
}
}
responses: {
key: "403";
value: {
description: "Returned when the user does not have permission to access the resource.";
}
}
responses: {
key: "404";
value: {
description: "Returned when the resource does not exist.";
schema: {
json_schema: {
type: STRING;
}
}
}
}
responses: {
key: "418";
value: {
description: "I'm a teapot.";
schema: {
json_schema: {
ref: ".grpc.gateway.examples.examplepb.NumericEnum";
}
}
}
}
}
}
}
security: {
security_requirement: {
key: "BasicAuth";
value: {};
}
security_requirement: {
key: "ApiKeyAuth";
value: {};
}
}
security: {
security_requirement: {
key: "OAuth2";
value: {
scope: "read";
scope: "write";
}
}
security_requirement: {
key: "ApiKeyAuth";
value: {};
}
}
};


// Intentionaly complicated message type to cover much features of Protobuf.
// Intentionaly complicated message type to cover many features of Protobuf.
// NEXT ID: 30
message ABitOfEverything {
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_schema) = {
json_schema: {
title: "A bit of everything"
description: "Intentionaly complicated message type to cover many features of Protobuf."
}
external_docs: {
url: "https://github.com/grpc-ecosystem/grpc-gateway";
description: "Find out more about ABitOfEverything";
Expand Down Expand Up @@ -155,7 +187,7 @@ message ABitOfEverything {

google.protobuf.Timestamp timestamp_value = 27;

// repeated enum value. it is comma-separated in query
// repeated enum value. it is comma-separated in query
repeated NumericEnum repeated_enum_value = 28;
}

Expand All @@ -174,7 +206,7 @@ enum NumericEnum {
// ZERO means 0
ZERO = 0;
// ONE means 1
ONE = 1;
ONE = 1;
}

// ABitOfEverything service is used to validate that APIs with complicated
Expand Down Expand Up @@ -217,31 +249,31 @@ service ABitOfEverythingService {
delete: "/v1/example/a_bit_of_everything/{uuid}"
};
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
security: {
security_requirement: {
key: "ApiKeyAuth";
value: {}
}
security_requirement: {
key: "OAuth2";
value: {
scope: "read";
scope: "write";
}
}
}
security: {
security_requirement: {
key: "ApiKeyAuth";
value: {}
}
security_requirement: {
key: "OAuth2";
value: {
scope: "read";
scope: "write";
}
}
}
};
}
rpc GetQuery(ABitOfEverything) returns (google.protobuf.Empty) {
option (google.api.http) = {
get: "/v1/example/a_bit_of_everything/query/{uuid}"
};
option (grpc.gateway.protoc_gen_swagger.options.openapiv2_operation) = {
deprecated: true // For testing purposes.
external_docs: {
url: "https://github.com/grpc-ecosystem/grpc-gateway";
description: "Find out more about GetQuery";
}
deprecated: true // For testing purposes.
external_docs: {
url: "https://github.com/grpc-ecosystem/grpc-gateway";
description: "Find out more about GetQuery";
}
};
}
// Echo allows posting a StringMessage value.
Expand Down Expand Up @@ -271,6 +303,24 @@ service ABitOfEverythingService {
url: "https://github.com/grpc-ecosystem/grpc-gateway";
description: "Find out more Echo";
}
responses: {
key: "503";
value: {
description: "Returned when the resource is temporarily unavailable.";
}
}
responses: {
// Overwrites global definition.
key: "404";
value: {
description: "Returned when the resource does not exist.";
schema: {
json_schema: {
type: INTEGER;
}
}
}
}
};
}
rpc DeepPathEcho(ABitOfEverything) returns (ABitOfEverything) {
Expand All @@ -296,20 +346,20 @@ service ABitOfEverythingService {
body: "data"
};
}
rpc PostWithEmptyBody(Body) returns (google.protobuf.Empty) {
option (google.api.http) = {
rpc PostWithEmptyBody(Body) returns (google.protobuf.Empty) {
option (google.api.http) = {
post: "/v2/example/postwithemptybody/{name}",
body: "*"
};
}
}
}
// camelCase and lowercase service names are valid but not recommended (use TitleCase instead)
service camelCaseServiceName {
rpc Empty(google.protobuf.Empty) returns (google.protobuf.Empty) {
option (google.api.http) = {
rpc Empty(google.protobuf.Empty) returns (google.protobuf.Empty) {
option (google.api.http) = {
get: "/v2/example/empty",
};
}
}
}
service AnotherServiceWithNoBindings {
rpc NoBindings(google.protobuf.Empty) returns (google.protobuf.Empty) {}
Expand Down
Loading