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.

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

Support disabling default response rendering #3006

Merged
merged 3 commits into from Nov 14, 2022
Merged

Support disabling default response rendering #3006

merged 3 commits into from Nov 14, 2022

Conversation

krak3n
Copy link
Contributor

@krak3n krak3n commented Nov 9, 2022

Fixes #2979

Changes

Addes a new disable_default_responses flag (default false) which disables the rendering of the default responses. This allows users to define different API responses for cases for where 200 is not the default response code from an existing API, for example it maybe 201.

The side effect of this is all responses would need to be defined when this option is set true.

krak3n
krak3n commented Nov 9, 2022
View reviewed changes
protoc-gen-openapiv2/internal/genopenapi/template_test.go
Comment on lines +3320 to +3328
// we have a protobufAny in a message but with automatic rendering of responses disabled
name: "protobufAny_referenced_in_message_with_default_responses_disabled",
args: args{
msgContainsAny: true,
regConfig: func(reg *descriptor.Registry) {
reg.SetDisableDefaultResponses(true)
},
},
wantNumDefinitions: 4,
Copy link
Contributor Author

Choose a reason for hiding this comment

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

Not exactly sure what this tests but it's here 😄

@krak3n krak3n mentioned this pull request Nov 9, 2022
Closed
johanbrandhorst
johanbrandhorst requested changes Nov 10, 2022
View reviewed changes
Copy link
Collaborator

@johanbrandhorst johanbrandhorst left a comment

Choose a reason for hiding this comment

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

LGTM! One thing, do you think you could add a small section to our docs about this new capability too? They live in https://github.com/grpc-ecosystem/grpc-gateway/blob/master/docs/docs/mapping/customizing_openapi_output.md. Thanks!

@krak3n
Copy link
Contributor Author

krak3n commented Nov 10, 2022

@johanbrandhorst add example output to the documentation 👍

johanbrandhorst
johanbrandhorst reviewed Nov 11, 2022
View reviewed changes
Copy link
Collaborator

@johanbrandhorst johanbrandhorst left a comment

Choose a reason for hiding this comment

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

Thanks for the docs, just a small idea.

docs/docs/mapping/customizing_openapi_output.md

### Disable default responses

By default a 200 OK response is rendered for each service operation. But it is possible to disable this and explicitly define your service's responses, using the `disable_default_responses` option. Allowed values are: `true`, `false`.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Could you just add a note somewhere to say that this does not change the behavior of the gateway itself, and must be coupled with a custom ForwardResponseWriter that adjusts the response to be an accurate reflection of the API behavior? Maybe link to the docs section that talks about changing the response code.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Added a note @johanbrandhorst

@johanbrandhorst johanbrandhorst merged commit 82da9d7 into grpc-ecosystem:master Nov 14, 2022
@johanbrandhorst
Copy link
Collaborator

Thanks for your contribution!

@krak3n krak3n deleted the feat/disable-default-responses branch November 14, 2022 23:06
andrewpollock pushed a commit to google/osv.dev that referenced this pull request Nov 28, 2022
@renovate-bot
Update module github.com/grpc-ecosystem/grpc-gateway/v2 to v2.14.0 (#859
e9f46a8 
)

[![Mend
Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com)

This PR contains the following updates:

| Package | Type | Update | Change |
|---|---|---|---|
|
[github.com/grpc-ecosystem/grpc-gateway/v2](https://togithub.com/grpc-ecosystem/grpc-gateway)
| require | minor | `v2.13.0` -> `v2.14.0` |

---

### Release Notes

<details>
<summary>grpc-ecosystem/grpc-gateway</summary>

###
[`v2.14.0`](https://togithub.com/grpc-ecosystem/grpc-gateway/releases/tag/v2.14.0)

[Compare
Source](https://togithub.com/grpc-ecosystem/grpc-gateway/compare/v2.13.0...v2.14.0)

#### New features

This release contains two significant new OpenAPIv2 generator features,
contributed by [@&#8203;krak3n](https://togithub.com/krak3n):

1. A new option to [disable rendering of 200 OK
responses](https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_openapi_output/#disable-default-responses).
This is useful if you define custom responses for your endpoints and you
modify the return code a forward response writer. Note that this does
not change the behavior of the gateway itself.
2. A new annotation for [defining header
parameters](https://grpc-ecosystem.github.io/grpc-gateway/docs/mapping/customizing_openapi_output/#custom-http-header-request-parameters).
This lets to define header parameters you want to be rendered in the
swagger.json output in addition to those defined in your API messages.
Note that this does not change the behavior of the gateway itself and
must be coupled with custom header parsing in your application.

#### What's Changed

- release: Update release.yml with option to workaround SLSA generator
failure by [@&#8203;asraa](https://togithub.com/asraa) in
[grpc-ecosystem/grpc-gateway#2987
- release: add a workflow_dispatch trigger for testing by
[@&#8203;asraa](https://togithub.com/asraa) in
[grpc-ecosystem/grpc-gateway#2989
- Use io/os instread of ioutil and use suitable verb by
[@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) in
[grpc-ecosystem/grpc-gateway#2991
- runtime pkg cleanup by
[@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) in
[grpc-ecosystem/grpc-gateway#2993
- mux: fix path components mutation by
[@&#8203;jonathaningram](https://togithub.com/jonathaningram) in
[grpc-ecosystem/grpc-gateway#3001
- fix: set consumes definition per operation by
[@&#8203;stomy13](https://togithub.com/stomy13) in
[grpc-ecosystem/grpc-gateway#2995
- protoc gen oas v2 cleanup by
[@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) in
[grpc-ecosystem/grpc-gateway#2996
- Use ReplaceAll instead of Replace with -1 pos by
[@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) in
[grpc-ecosystem/grpc-gateway#3003
- Errors cleanup by
[@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) in
[grpc-ecosystem/grpc-gateway#3004
- Cleanup by
[@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) in
[grpc-ecosystem/grpc-gateway#3012
- Support disabling default response rendering by
[@&#8203;krak3n](https://togithub.com/krak3n) in
[grpc-ecosystem/grpc-gateway#3006
- Support request header parameters by
[@&#8203;krak3n](https://togithub.com/krak3n) in
[grpc-ecosystem/grpc-gateway#3010

#### New Contributors

- [@&#8203;asraa](https://togithub.com/asraa) made their first
contribution in
[grpc-ecosystem/grpc-gateway#2987
- [@&#8203;sashamelentyev](https://togithub.com/sashamelentyev) made
their first contribution in
[grpc-ecosystem/grpc-gateway#2991
- [@&#8203;stomy13](https://togithub.com/stomy13) made their first
contribution in
[grpc-ecosystem/grpc-gateway#2995
- [@&#8203;krak3n](https://togithub.com/krak3n) made their first
contribution in
[grpc-ecosystem/grpc-gateway#3006

**Full Changelog**:
grpc-ecosystem/grpc-gateway@v2.13.0...v2.14.0

</details>

---

### Configuration

📅 **Schedule**: Branch creation - "before 6am on monday" in timezone
Australia/Sydney, Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you
are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR has been generated by [Mend
Renovate](https://www.mend.io/free-developer-tools/renovate/). View
repository job log
[here](https://app.renovatebot.com/dashboard#github/google/osv.dev).

<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNC4zNy4wIiwidXBkYXRlZEluVmVyIjoiMzQuMzcuMCJ9-->
@zshainsky
Copy link

Hi all what would it take to add this to the bazel protoc_gen_openapiv2 command? Would that be just a simple update to the defs.bzl file?

@johanbrandhorst
Copy link
Collaborator

Yep, that should be it. We should've added it when we added this flag, oops 😬

@zshainsky
Copy link

Thanks @johanbrandhorst want me to open an issue for this?

@rajukrishnamurthy rajukrishnamurthy mentioned this pull request Mar 19, 2024
Closed
@johanbrandhorst
Copy link
Collaborator

Seems like @rajukrishnamurthy beat you to it in #4123.

@rajukrishnamurthy rajukrishnamurthy mentioned this pull request Mar 20, 2024
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@johanbrandhorst johanbrandhorst johanbrandhorst approved these changes

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Option to turn off default 200 response generation in protoc-gen-openapiv2
3 participants
@krak3n @johanbrandhorst @zshainsky