Field and schema extensions

[james-o-johnstone]

References to other Issues or PRs

Fixes #1791

Have you read the Contributing Guidelines?

Yes

Brief description of what is fixed or changed

Add extensions to field and schema annotations.

Other comments

Support for extensions was added in #1033 but not for field/schema annotations.

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[johanbrandhorst]

This looks great! I had some small questions. To fix the CLA bot you'll need to force push over any old commits on an account not linked to github.

[johanbrandhorst]

Which section within the swagger spec does this map to: https://swagger.io/docs/specification/2-0/swagger-extensions/? Just want to make sure we're not adding these somewhere they don't belong.

[james-o-johnstone]

If I'm understanding correctly, this is used for FieldOptions annotations, I think this maps to the swagger schema object which supports extensions according to: https://github.com/OAI/OpenAPI-Specification/blob/3.0.0/versions/2.0.md#patterned-objects-9. Example:

message AMessage {
  string id = 1 [
    option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_field) = {
      extensions: {
        key: "x-something-something";
        value {
          string_value: "yadda";
        }
      }
    }
  ]
};

However, in revisiting this I've realised that the JSONSchema defined here is also part of the Schema type defined above, so it looks like it would be possible to only add the extensions field in this JSONSchema message and use in schema annotations like this:

message AMessage {
  option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_schema) = {
    json_schema: {
      extensions: {
        key: "x-something-something";
        value {
          string_value: "yadda";
        }
      }
    }
  };
}

[johanbrandhorst]

That sounds reasonable to me

[james-o-johnstone]

This looks great! I had some small questions. To fix the CLA bot you'll need to force push over any old commits on an account not linked to github.

Thanks. Regarding CLA we are working on setting this up internally as I will need to submit on behalf of my employer, we don't yet have the necessary google groups etc. set up.

[google-cla]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed (or fixed any issues), please reply here with @googlebot I signed it! and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

ℹ️ Googlers: Go here for more info.

[codecov-commenter]

Codecov Report

Merging #2418 (e154b58) into master (ea4029e) will increase coverage by 0.14%.
The diff coverage is 44.44%.

@@            Coverage Diff             @@
##           master    #2418      +/-   ##
==========================================
+ Coverage   61.00%   61.14%   +0.14%     
==========================================
  Files          38       38              
  Lines        4952     4970      +18     
==========================================
+ Hits         3021     3039      +18     
+ Misses       1596     1593       -3     
- Partials      335      338       +3     

Impacted Files	Coverage Δ
protoc-gen-openapiv2/internal/genopenapi/types.go	74.35% <ø> (ø)
...otoc-gen-openapiv2/internal/genopenapi/template.go	62.71% <41.66%> (-0.16%)	⬇️
...toc-gen-openapiv2/internal/genopenapi/generator.go	43.18% <50.00%> (+8.26%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ea4029e...e154b58. Read the comment docs.

[drewwells]

Looking forward to this getting merged. Will it happen soon?

[johanbrandhorst]

Unfortunately we're still waiting for CLA approval here. Note that the Google CLA bot has been acting up a bit lately so I may need to manually override it, as long as @james-o-johnstone can provide some evidence that he's signed it I'm happy.

[drewwells]

Unfortunately we're still waiting for CLA approval here. Note that the Google CLA bot has been acting up a bit lately so I may need to manually override it, as long as @james-o-johnstone can provide some evidence that he's signed it I'm happy.

I don’t have context on these changes. If they are all good, I can definitely open a new PR , copy the changes, and sign the CLA. Pretty sure I already signed the CLA

[johanbrandhorst]

I wouldn't be comfortable with simply copy-pasting the contents of the PR without explicit consent from @james-o-johnstone. If they're unable to sign the CLA but can consent to use copying the contribution we could make it happen in a separate PR.

[james-o-johnstone]

Hey, sorry I'm still waiting on the contributor group to be set up at my company before I can sign the CLA, I will chase this up today.

[drewwells]

Hey, sorry I'm still waiting on the contributor group to be set up at my company before I can sign the CLA, I will chase this up today.

Thanks @james-o-johnstone

[james-o-johnstone]

Hey, sorry for the delay on this. This is still ticking along internally, CLA has now been reviewed by legal team and hopefully the wait won't be too much longer before I can sign the CLA. Thanks for your patience.

[johanbrandhorst]

Thanks for the update James, in the meantime, maybe you want to try rebasing on master?

[C0mbatwombat]

Thanks James for the hard work, I am waiting eagerly for this change 👍

[johanbrandhorst]

There is now an alternative implementation to hiding fields/RPCs in #2578. We probably only want to merge one, so would interested parties weigh in on which they would prefer?

[james-o-johnstone]

@googlebot I signed it!

[johanbrandhorst]

LGTM 🎉

[johanbrandhorst]

Ah one final thing I would ask, could you add something to document this new feature? The docs for the openapi options are found here: https://github.com/grpc-ecosystem/grpc-gateway/blob/master/docs/docs/mapping/customizing_openapi_output.md.

[johanbrandhorst]

Thanks for your contribution! I'm extremely pleased to have this merged finally :).