Skip to content

Commit 8cc3a55

Browse files
ivucicaachew22
ivucica
authored and
achew22
committed
Add custom options to allow more control of swagger/openapi output (grpc-ecosystem#145)
Creates additional options that can be applied to RPCs and messages that provide additional information in the OpenAPIv2 spec. These new options allow for the inclusion of Swagger object information (maps to a .proto file): * `info` * `host` * `base_path` * `schemes` * `consumes` * `produces` * `external_docs` Service information: * `tags` * `summary` * `description` * `external_docs` * `operation_id` * `consumes` * `produces` * `schemes` Operation information (maps to a method): * `tags` * `summary` * `description` * `external_docs` * `operation_id` * `consumes` * `produces` * `schemes` Schema information (maps to a message): * `json_schema` * `descriptor` * `read_only` * `external_docs` * `example` Additionally: * Change from 'Swagger: ' to 'OpenAPI: ' prefix. It should also be relatively simple to add any field that is missing to the new OpenAPI proto objects.
1 parent b0be3cd commit 8cc3a55

22 files changed

+1612
-197
lines changed

‎Makefile

+9-2
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,9 @@ OUTPUT_DIR=_output
4343
RUNTIME_PROTO=runtime/internal/stream_chunk.proto
4444
RUNTIME_GO=$(RUNTIME_PROTO:.proto=.pb.go)
4545

46+
OPENAPIV2_PROTO=protoc-gen-swagger/options/openapiv2.proto protoc-gen-swagger/options/annotations.proto
47+
OPENAPIV2_GO=$(OPENAPIV2_PROTO:.proto=.pb.go)
48+
4649
PKGMAP=Mgoogle/protobuf/descriptor.proto=$(GO_PLUGIN_PKG)/descriptor,Mexamples/sub/message.proto=$(PKG)/examples/sub
4750
ADDITIONAL_FLAGS=
4851
ifneq "$(GATEWAY_PLUGIN_FLAGS)" ""
@@ -83,17 +86,20 @@ generate: $(RUNTIME_GO)
8386

8487
.SUFFIXES: .go .proto
8588

86-
$(GO_PLUGIN):
89+
$(GO_PLUGIN):
8790
go get $(GO_PLUGIN_PKG)
8891
go build -o $@ $(GO_PLUGIN_PKG)
8992

9093
$(RUNTIME_GO): $(RUNTIME_PROTO) $(GO_PLUGIN)
9194
protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP):. $(RUNTIME_PROTO)
9295

96+
$(OPENAPIV2_GO): $(OPENAPIV2_PROTO) $(GO_PLUGIN)
97+
protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP):$(GOPATH)/src $(OPENAPIV2_PROTO)
98+
9399
$(GATEWAY_PLUGIN): $(RUNTIME_GO) $(GATEWAY_PLUGIN_SRC)
94100
go build -o $@ $(GATEWAY_PLUGIN_PKG)
95101

96-
$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC)
102+
$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC) $(OPENAPIV2_GO)
97103
go build -o $@ $(SWAGGER_PLUGIN_PKG)
98104

99105
$(EXAMPLE_SVCSRCS): $(GO_PLUGIN) $(EXAMPLES)
@@ -143,5 +149,6 @@ realclean: distclean
143149
rm -f $(GO_PLUGIN)
144150
rm -f $(SWAGGER_PLUGIN)
145151
rm -f $(EXAMPLE_CLIENT_SRCS)
152+
rm -f $(OPENAPIV2_GO)
146153

147154
.PHONY: generate examples test lint clean distclean realclean

‎examples/clients/abe/a_bit_of_everything_nested.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/*
2-
* examples/examplepb/a_bit_of_everything.proto
2+
* A Bit of Everything
33
*
44
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
55
*
6-
* OpenAPI spec version: version not set
7-
*
6+
* OpenAPI spec version: 1.0
7+
* Contact: [email protected]
88
* Generated by: https://github.com/swagger-api/swagger-codegen.git
99
*/
1010

‎examples/clients/abe/a_bit_of_everything_service_api.go

+42-28
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/*
2-
* examples/examplepb/a_bit_of_everything.proto
2+
* A Bit of Everything
33
*
44
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
55
*
6-
* OpenAPI spec version: version not set
7-
*
6+
* OpenAPI spec version: 1.0
7+
* Contact: [email protected]
88
* Generated by: https://github.com/swagger-api/swagger-codegen.git
99
*/
1010

@@ -91,7 +91,7 @@ func (a ABitOfEverythingServiceApi) Create(floatValue float32, doubleValue float
9191
}
9292

9393
// to determine the Content-Type header
94-
localVarHttpContentTypes := []string{ "application/json", }
94+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
9595

9696
// set Content-Type header
9797
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -101,6 +101,7 @@ func (a ABitOfEverythingServiceApi) Create(floatValue float32, doubleValue float
101101
// to determine the Accept header
102102
localVarHttpHeaderAccepts := []string{
103103
"application/json",
104+
"application/x-foo-mime",
104105
}
105106

106107
// set Accept header
@@ -150,7 +151,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
150151
}
151152

152153
// to determine the Content-Type header
153-
localVarHttpContentTypes := []string{ "application/json", }
154+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
154155

155156
// set Content-Type header
156157
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -160,6 +161,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
160161
// to determine the Accept header
161162
localVarHttpHeaderAccepts := []string{
162163
"application/json",
164+
"application/x-foo-mime",
163165
}
164166

165167
// set Accept header
@@ -213,7 +215,7 @@ func (a ABitOfEverythingServiceApi) DeepPathEcho(singleNestedName string, body E
213215
}
214216

215217
// to determine the Content-Type header
216-
localVarHttpContentTypes := []string{ "application/json", }
218+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
217219

218220
// set Content-Type header
219221
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -223,6 +225,7 @@ func (a ABitOfEverythingServiceApi) DeepPathEcho(singleNestedName string, body E
223225
// to determine the Accept header
224226
localVarHttpHeaderAccepts := []string{
225227
"application/json",
228+
"application/x-foo-mime",
226229
}
227230

228231
// set Accept header
@@ -275,7 +278,7 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
275278
}
276279

277280
// to determine the Content-Type header
278-
localVarHttpContentTypes := []string{ "application/json", }
281+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
279282

280283
// set Content-Type header
281284
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -285,6 +288,7 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
285288
// to determine the Accept header
286289
localVarHttpHeaderAccepts := []string{
287290
"application/json",
291+
"application/x-foo-mime",
288292
}
289293

290294
// set Accept header
@@ -311,7 +315,8 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
311315
}
312316

313317
/**
314-
*
318+
* Echo allows posting a StringMessage value.
319+
* It also exposes multiple bindings. This makes it useful when validating that the OpenAPI v2 API description exposes documentation correctly on all paths defined as additional_bindings in the proto.
315320
*
316321
* @param value
317322
* @return *SubStringMessage
@@ -335,7 +340,7 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
335340
}
336341

337342
// to determine the Content-Type header
338-
localVarHttpContentTypes := []string{ "application/json", }
343+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
339344

340345
// set Content-Type header
341346
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -345,6 +350,7 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
345350
// to determine the Accept header
346351
localVarHttpHeaderAccepts := []string{
347352
"application/json",
353+
"application/x-foo-mime",
348354
}
349355

350356
// set Accept header
@@ -371,14 +377,15 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
371377
}
372378

373379
/**
374-
*
380+
* Echo allows posting a StringMessage value.
381+
* It also exposes multiple bindings. This makes it useful when validating that the OpenAPI v2 API description exposes documentation correctly on all paths defined as additional_bindings in the proto.
375382
*
376-
* @param value
383+
* @param body
377384
* @return *SubStringMessage
378385
*/
379-
func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *APIResponse, error) {
386+
func (a ABitOfEverythingServiceApi) Echo2(body string) (*SubStringMessage, *APIResponse, error) {
380387

381-
var localVarHttpMethod = strings.ToUpper("Get")
388+
var localVarHttpMethod = strings.ToUpper("Post")
382389
// create path and map variables
383390
localVarPath := a.Configuration.BasePath + "/v2/example/echo"
384391

@@ -392,10 +399,9 @@ func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *AP
392399
for key := range a.Configuration.DefaultHeader {
393400
localVarHeaderParams[key] = a.Configuration.DefaultHeader[key]
394401
}
395-
localVarQueryParams.Add("value", a.Configuration.APIClient.ParameterToString(value, ""))
396402

397403
// to determine the Content-Type header
398-
localVarHttpContentTypes := []string{ "application/json", }
404+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
399405

400406
// set Content-Type header
401407
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -405,19 +411,22 @@ func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *AP
405411
// to determine the Accept header
406412
localVarHttpHeaderAccepts := []string{
407413
"application/json",
414+
"application/x-foo-mime",
408415
}
409416

410417
// set Accept header
411418
localVarHttpHeaderAccept := a.Configuration.APIClient.SelectHeaderAccept(localVarHttpHeaderAccepts)
412419
if localVarHttpHeaderAccept != "" {
413420
localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
414421
}
422+
// body params
423+
localVarPostBody = &body
415424
var successPayload = new(SubStringMessage)
416425
localVarHttpResponse, err := a.Configuration.APIClient.CallAPI(localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)
417426

418427
var localVarURL, _ = url.Parse(localVarPath)
419428
localVarURL.RawQuery = localVarQueryParams.Encode()
420-
var localVarAPIResponse = &APIResponse{Operation: "Echo_0", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
429+
var localVarAPIResponse = &APIResponse{Operation: "Echo2", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
421430
if localVarHttpResponse != nil {
422431
localVarAPIResponse.Response = localVarHttpResponse.RawResponse
423432
localVarAPIResponse.Payload = localVarHttpResponse.Body()
@@ -431,14 +440,15 @@ func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *AP
431440
}
432441

433442
/**
434-
*
443+
* Echo allows posting a StringMessage value.
444+
* It also exposes multiple bindings. This makes it useful when validating that the OpenAPI v2 API description exposes documentation correctly on all paths defined as additional_bindings in the proto.
435445
*
436-
* @param body
446+
* @param value
437447
* @return *SubStringMessage
438448
*/
439-
func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *APIResponse, error) {
449+
func (a ABitOfEverythingServiceApi) Echo3(value string) (*SubStringMessage, *APIResponse, error) {
440450

441-
var localVarHttpMethod = strings.ToUpper("Post")
451+
var localVarHttpMethod = strings.ToUpper("Get")
442452
// create path and map variables
443453
localVarPath := a.Configuration.BasePath + "/v2/example/echo"
444454

@@ -452,9 +462,10 @@ func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *API
452462
for key := range a.Configuration.DefaultHeader {
453463
localVarHeaderParams[key] = a.Configuration.DefaultHeader[key]
454464
}
465+
localVarQueryParams.Add("value", a.Configuration.APIClient.ParameterToString(value, ""))
455466

456467
// to determine the Content-Type header
457-
localVarHttpContentTypes := []string{ "application/json", }
468+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
458469

459470
// set Content-Type header
460471
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -464,21 +475,20 @@ func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *API
464475
// to determine the Accept header
465476
localVarHttpHeaderAccepts := []string{
466477
"application/json",
478+
"application/x-foo-mime",
467479
}
468480

469481
// set Accept header
470482
localVarHttpHeaderAccept := a.Configuration.APIClient.SelectHeaderAccept(localVarHttpHeaderAccepts)
471483
if localVarHttpHeaderAccept != "" {
472484
localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
473485
}
474-
// body params
475-
localVarPostBody = &body
476486
var successPayload = new(SubStringMessage)
477487
localVarHttpResponse, err := a.Configuration.APIClient.CallAPI(localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)
478488

479489
var localVarURL, _ = url.Parse(localVarPath)
480490
localVarURL.RawQuery = localVarQueryParams.Encode()
481-
var localVarAPIResponse = &APIResponse{Operation: "Echo_1", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
491+
var localVarAPIResponse = &APIResponse{Operation: "Echo3", Method: localVarHttpMethod, RequestURL: localVarURL.String()}
482492
if localVarHttpResponse != nil {
483493
localVarAPIResponse.Response = localVarHttpResponse.RawResponse
484494
localVarAPIResponse.Payload = localVarHttpResponse.Body()
@@ -566,7 +576,7 @@ func (a ABitOfEverythingServiceApi) GetQuery(uuid string, singleNestedName strin
566576

567577

568578
// to determine the Content-Type header
569-
localVarHttpContentTypes := []string{ "application/json", }
579+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
570580

571581
// set Content-Type header
572582
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -576,6 +586,7 @@ func (a ABitOfEverythingServiceApi) GetQuery(uuid string, singleNestedName strin
576586
// to determine the Accept header
577587
localVarHttpHeaderAccepts := []string{
578588
"application/json",
589+
"application/x-foo-mime",
579590
}
580591

581592
// set Accept header
@@ -626,7 +637,7 @@ func (a ABitOfEverythingServiceApi) Lookup(uuid string) (*ExamplepbABitOfEveryth
626637
}
627638

628639
// to determine the Content-Type header
629-
localVarHttpContentTypes := []string{ "application/json", }
640+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
630641

631642
// set Content-Type header
632643
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -636,6 +647,7 @@ func (a ABitOfEverythingServiceApi) Lookup(uuid string) (*ExamplepbABitOfEveryth
636647
// to determine the Accept header
637648
localVarHttpHeaderAccepts := []string{
638649
"application/json",
650+
"application/x-foo-mime",
639651
}
640652

641653
// set Accept header
@@ -684,7 +696,7 @@ func (a ABitOfEverythingServiceApi) Timeout() (*ProtobufEmpty, *APIResponse, err
684696
}
685697

686698
// to determine the Content-Type header
687-
localVarHttpContentTypes := []string{ "application/json", }
699+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
688700

689701
// set Content-Type header
690702
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -694,6 +706,7 @@ func (a ABitOfEverythingServiceApi) Timeout() (*ProtobufEmpty, *APIResponse, err
694706
// to determine the Accept header
695707
localVarHttpHeaderAccepts := []string{
696708
"application/json",
709+
"application/x-foo-mime",
697710
}
698711

699712
// set Accept header
@@ -745,7 +758,7 @@ func (a ABitOfEverythingServiceApi) Update(uuid string, body ExamplepbABitOfEver
745758
}
746759

747760
// to determine the Content-Type header
748-
localVarHttpContentTypes := []string{ "application/json", }
761+
localVarHttpContentTypes := []string{ "application/json", "application/x-foo-mime", }
749762

750763
// set Content-Type header
751764
localVarHttpContentType := a.Configuration.APIClient.SelectHeaderContentType(localVarHttpContentTypes)
@@ -755,6 +768,7 @@ func (a ABitOfEverythingServiceApi) Update(uuid string, body ExamplepbABitOfEver
755768
// to determine the Accept header
756769
localVarHttpHeaderAccepts := []string{
757770
"application/json",
771+
"application/x-foo-mime",
758772
}
759773

760774
// set Accept header

‎examples/clients/abe/api_client.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/*
2-
* examples/examplepb/a_bit_of_everything.proto
2+
* A Bit of Everything
33
*
44
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
55
*
6-
* OpenAPI spec version: version not set
7-
*
6+
* OpenAPI spec version: 1.0
7+
* Contact: [email protected]
88
* Generated by: https://github.com/swagger-api/swagger-codegen.git
99
*/
1010

‎examples/clients/abe/api_response.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/*
2-
* examples/examplepb/a_bit_of_everything.proto
2+
* A Bit of Everything
33
*
44
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
55
*
6-
* OpenAPI spec version: version not set
7-
*
6+
* OpenAPI spec version: 1.0
7+
* Contact: [email protected]
88
* Generated by: https://github.com/swagger-api/swagger-codegen.git
99
*/
1010

‎examples/clients/abe/configuration.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/*
2-
* examples/examplepb/a_bit_of_everything.proto
2+
* A Bit of Everything
33
*
44
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
55
*
6-
* OpenAPI spec version: version not set
7-
*
6+
* OpenAPI spec version: 1.0
7+
* Contact: [email protected]
88
* Generated by: https://github.com/swagger-api/swagger-codegen.git
99
*/
1010

‎examples/clients/abe/examplepb_a_bit_of_everything.go

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
/*
2-
* examples/examplepb/a_bit_of_everything.proto
2+
* A Bit of Everything
33
*
44
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
55
*
6-
* OpenAPI spec version: version not set
7-
*
6+
* OpenAPI spec version: 1.0
7+
* Contact: [email protected]
88
* Generated by: https://github.com/swagger-api/swagger-codegen.git
99
*/
1010

0 commit comments

Comments
 (0)