Add a FAQ #550
Add a FAQ #550
Conversation
README.md
Outdated
| @@ -239,6 +239,16 @@ But patch is welcome. | |||
| # Contribution | |||
| See [CONTRIBUTING.md](http://github.com/grpc-ecosystem/grpc-gateway/blob/master/CONTRIBUTING.md). | |||
|
|
|||
| # FAQ | |||
|
|
|||
| > Why are the models in the swagger spec prefixed with the last bit of the proto package name? Is there a reason for this? I find this pretty ugly tbh and don’t see the advantage. | |||
There was a problem hiding this comment.
I would shorten the question to: Why are the models in the swagger specification prefixed with the last part of the proto package name?
README.md
Outdated
|
|
||
| The reason to generate the prefixes is that we don't have a guaranteed unique namespace. If two packages produce different Foo messages then we will have trouble. | ||
|
|
||
| > Why not strip the prefix if it isn't necessary? |
There was a problem hiding this comment.
I suggest shortening: Why not strip the prefix?
README.md
Outdated
|
|
||
| > Why not strip the prefix if it isn't necessary? | ||
|
|
||
| I tried that, but the problem is that if you do that then when you add a message in that happens to conflict it will break code that is very far away from the code that changed. This is in an effort to adhere to the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment). |
There was a problem hiding this comment.
Just a bit more general:
When a message is added which happens to conflict with another message (e.g. by importing a message with the same name from a different package) it will break code that is very far away from the code that changed. This is in an effort to adhere to the [principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment).
Moving it into its own file in the docs section
|
@lukasmalkmus, sorry for being so slow to respond. What do you think about my updated FAQ entries? |
|
No worries. Looks good. |
@lukasmalkmus, can you please review this? I would love your input.
Fixes #525