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

Jump to bottom

add custom options to allow more control of swagger/openapi output #145

Merged
merged 26 commits into from
Nov 3, 2017
Merged

add custom options to allow more control of swagger/openapi output #145

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
6ff06d8
Apply additional Swagger properties using JSON.
ivucica May 7, 2016
fcc2dca
Swagger: Replaced '<!-- ... -->' for raw JSON with last paragraph 'Sw…
ivucica May 7, 2016
20a6d40
Change from 'Swagger: ' to 'OpenAPI: ' prefix.
ivucica May 7, 2016
321663d
WIP: Use a proto option to describe whether a Swagger Operation is de…
ivucica Feb 13, 2017
7043966
WIP: Setting API properties through an option.
ivucica Mar 7, 2017
cdc1094
WIP: Correctly reserve fields. Update link. TODO: merge with commit M…
ivucica Oct 27, 2017
41b436f
WIP: Refer to the specification as OpenAPI v2, not Swagger.
ivucica Oct 27, 2017
74cd394
WIP: Clean up after OpenAPIv2 options proto generation.
ivucica Oct 27, 2017
549ccee
WIP: JSON is disappearing from the output protos.
ivucica Oct 27, 2017
6b2b321
WIP: Fix typo 'want an Swagger' -> 'want a Swagger object'.
ivucica Oct 27, 2017
db4a056
WIP: Process all remaining fields of the OpenAPI v2 Swagger object.
ivucica Oct 27, 2017
7697bcf
WIP: ExternalDocs belongs on OpenAPIv2's Swagger object, not on the I…
ivucica Oct 27, 2017
162c375
WIP: Remove use of JSON. Introduce schema and tag object. Support ext…
ivucica Oct 28, 2017
b53579c
WIP: Add built annotations.pb.go and openapiv2.pb.go.
ivucica Oct 28, 2017
60d116f
WIP: go fmt on protoc-gen-swagger.
ivucica Oct 28, 2017
d509096
WIP: Provide a more unique operation ID in case of additional bindings.
ivucica Oct 28, 2017
3949620
WIP: Try to fix integration test by removing 'host' from the Swagger …
ivucica Oct 28, 2017
a386e97
WIP: Remove swaggerExtrasRegexp.
ivucica Oct 29, 2017
290f777
WIP: Move error checking for extractSchemaOptionFromMessageDescriptor…
ivucica Oct 29, 2017
97ee19b
WIP: Fix typo: 'want a Schema'.
ivucica Oct 29, 2017
ceb4c4e
Assign IDs for proto options extensions.
ivucica Nov 1, 2017
099fda5
Move test definitions for options-based extension to Swagger output f…
ivucica Nov 1, 2017
d7b0ba4
Undo commenting out dependency on EXAMPLE_CLIENT_SRCS.
ivucica Nov 2, 2017
d7a9a69
Change the proto package to start with 'grpc.gateway', as seems to be…
ivucica Nov 2, 2017
84c3046
Add a comment about all IDs being ok to be the same.
ivucica Nov 2, 2017
a543b9e
Regenerated Swagger-generated clients.
ivucica Nov 2, 2017
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
11 changes: 9 additions & 2 deletions Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,9 @@ OUTPUT_DIR=_output
RUNTIME_PROTO=runtime/internal/stream_chunk.proto
RUNTIME_GO=$(RUNTIME_PROTO:.proto=.pb.go)

OPENAPIV2_PROTO=protoc-gen-swagger/options/openapiv2.proto protoc-gen-swagger/options/annotations.proto
OPENAPIV2_GO=$(OPENAPIV2_PROTO:.proto=.pb.go)

PKGMAP=Mgoogle/protobuf/descriptor.proto=$(GO_PLUGIN_PKG)/descriptor,Mexamples/sub/message.proto=$(PKG)/examples/sub
ADDITIONAL_FLAGS=
ifneq "$(GATEWAY_PLUGIN_FLAGS)" ""
Expand Down Expand Up @@ -83,17 +86,20 @@ generate: $(RUNTIME_GO)

.SUFFIXES: .go .proto

$(GO_PLUGIN):
$(GO_PLUGIN):
go get $(GO_PLUGIN_PKG)
go build -o $@ $(GO_PLUGIN_PKG)

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

$(OPENAPIV2_GO): $(OPENAPIV2_PROTO) $(GO_PLUGIN)
protoc -I $(PROTOC_INC_PATH) --plugin=$(GO_PLUGIN) -I. --go_out=$(PKGMAP):$(GOPATH)/src $(OPENAPIV2_PROTO)

$(GATEWAY_PLUGIN): $(RUNTIME_GO) $(GATEWAY_PLUGIN_SRC)
go build -o $@ $(GATEWAY_PLUGIN_PKG)

$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC)
$(SWAGGER_PLUGIN): $(SWAGGER_PLUGIN_SRC) $(OPENAPIV2_GO)
go build -o $@ $(SWAGGER_PLUGIN_PKG)

$(EXAMPLE_SVCSRCS): $(GO_PLUGIN) $(EXAMPLES)
Expand Down Expand Up @@ -143,5 +149,6 @@ realclean: distclean
rm -f $(GO_PLUGIN)
rm -f $(SWAGGER_PLUGIN)
rm -f $(EXAMPLE_CLIENT_SRCS)
rm -f $(OPENAPIV2_GO)

.PHONY: generate examples test lint clean distclean realclean
6 changes: 3 additions & 3 deletions examples/clients/abe/a_bit_of_everything_nested.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/*
* examples/examplepb/a_bit_of_everything.proto
* A Bit of Everything
*
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: version not set
*
* OpenAPI spec version: 1.0
* Contact: none@example.com
* Generated by: https://github.com/swagger-api/swagger-codegen.git
*/

Expand Down
70 changes: 42 additions & 28 deletions examples/clients/abe/a_bit_of_everything_service_api.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/*
* examples/examplepb/a_bit_of_everything.proto
* A Bit of Everything
*
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: version not set
*
* OpenAPI spec version: 1.0
* Contact: none@example.com
* Generated by: https://github.com/swagger-api/swagger-codegen.git
*/

Expand Down Expand Up @@ -91,7 +91,7 @@ func (a ABitOfEverythingServiceApi) Create(floatValue float32, doubleValue float
}

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

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

// set Accept header
Expand Down Expand Up @@ -150,7 +151,7 @@ func (a ABitOfEverythingServiceApi) CreateBody(body ExamplepbABitOfEverything) (
}

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

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

// set Accept header
Expand Down Expand Up @@ -213,7 +215,7 @@ func (a ABitOfEverythingServiceApi) DeepPathEcho(singleNestedName string, body E
}

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

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

// set Accept header
Expand Down Expand Up @@ -275,7 +278,7 @@ func (a ABitOfEverythingServiceApi) Delete(uuid string) (*ProtobufEmpty, *APIRes
}

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

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

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

/**
*
* Echo allows posting a StringMessage value.
* 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.
*
* @param value
* @return *SubStringMessage
Expand All @@ -335,7 +340,7 @@ func (a ABitOfEverythingServiceApi) Echo(value string) (*SubStringMessage, *APIR
}

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

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

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

/**
*
* Echo allows posting a StringMessage value.
* 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.
*
* @param value
* @param body
* @return *SubStringMessage
*/
func (a ABitOfEverythingServiceApi) Echo_1(value string) (*SubStringMessage, *APIResponse, error) {
func (a ABitOfEverythingServiceApi) Echo2(body string) (*SubStringMessage, *APIResponse, error) {

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

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

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

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

// set Accept header
localVarHttpHeaderAccept := a.Configuration.APIClient.SelectHeaderAccept(localVarHttpHeaderAccepts)
if localVarHttpHeaderAccept != "" {
localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
}
// body params
localVarPostBody = &body
var successPayload = new(SubStringMessage)
localVarHttpResponse, err := a.Configuration.APIClient.CallAPI(localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)

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

/**
*
* Echo allows posting a StringMessage value.
* 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.
*
* @param body
* @param value
* @return *SubStringMessage
*/
func (a ABitOfEverythingServiceApi) Echo_2(body string) (*SubStringMessage, *APIResponse, error) {
func (a ABitOfEverythingServiceApi) Echo3(value string) (*SubStringMessage, *APIResponse, error) {

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

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

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

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

// set Accept header
localVarHttpHeaderAccept := a.Configuration.APIClient.SelectHeaderAccept(localVarHttpHeaderAccepts)
if localVarHttpHeaderAccept != "" {
localVarHeaderParams["Accept"] = localVarHttpHeaderAccept
}
// body params
localVarPostBody = &body
var successPayload = new(SubStringMessage)
localVarHttpResponse, err := a.Configuration.APIClient.CallAPI(localVarPath, localVarHttpMethod, localVarPostBody, localVarHeaderParams, localVarQueryParams, localVarFormParams, localVarFileName, localVarFileBytes)

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


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

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

// set Accept header
Expand Down Expand Up @@ -626,7 +637,7 @@ func (a ABitOfEverythingServiceApi) Lookup(uuid string) (*ExamplepbABitOfEveryth
}

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

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

// set Accept header
Expand Down Expand Up @@ -684,7 +696,7 @@ func (a ABitOfEverythingServiceApi) Timeout() (*ProtobufEmpty, *APIResponse, err
}

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

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

// set Accept header
Expand Down Expand Up @@ -745,7 +758,7 @@ func (a ABitOfEverythingServiceApi) Update(uuid string, body ExamplepbABitOfEver
}

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

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

// set Accept header
Expand Down
6 changes: 3 additions & 3 deletions examples/clients/abe/api_client.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/*
* examples/examplepb/a_bit_of_everything.proto
* A Bit of Everything
*
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: version not set
*
* OpenAPI spec version: 1.0
* Contact: none@example.com
* Generated by: https://github.com/swagger-api/swagger-codegen.git
*/

Expand Down
6 changes: 3 additions & 3 deletions examples/clients/abe/api_response.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/*
* examples/examplepb/a_bit_of_everything.proto
* A Bit of Everything
*
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: version not set
*
* OpenAPI spec version: 1.0
* Contact: none@example.com
* Generated by: https://github.com/swagger-api/swagger-codegen.git
*/

Expand Down
6 changes: 3 additions & 3 deletions examples/clients/abe/configuration.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
/*
* examples/examplepb/a_bit_of_everything.proto
* A Bit of Everything
*
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: version not set
*
* OpenAPI spec version: 1.0
* Contact: none@example.com
* Generated by: https://github.com/swagger-api/swagger-codegen.git
*/

Expand Down
6 changes: 3 additions & 3 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
@@ -1,10 +1,10 @@
/*
* examples/examplepb/a_bit_of_everything.proto
* A Bit of Everything
*
* No description provided (generated by Swagger Codegen https://github.com/swagger-api/swagger-codegen)
*
* OpenAPI spec version: version not set
*
* OpenAPI spec version: 1.0
* Contact: none@example.com
* Generated by: https://github.com/swagger-api/swagger-codegen.git
*/

Expand Down
Loading