microsoft / microsoft/typespec
Review inlining and naming choices in OpenAPI
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
#463 refactors how we decide what to inline and what names to use and puts it all in one place, but it doesn't change behavior except to fix obvious bugs.
***EDIT*** See first comment for proposal.
---
Bit of a brain dump here. I will think on it and try to build a proposal.
Briefly, we currently:
* Inline anonymous types, including arrays, tuples, anonymous unions, anonymous models, etc.
* Inline template instantiations with no `@friendlyName`,
* We effectively provide a default `@friendlyName` of Type_Arg1_...ArgN if the args are not inlined and not themselves template instantiations.
* Strip off root `Cadl` and service namespace
Issues:
- friendlyName drops namespace
- friendlyName can easily cause collisions (we will now produce an error if there's a collision)
- Weird that `Foo` is inlined but `Foo>` is not (absent any explicit friendly names). This feels like the sort of quirk that will bite us when we go to change it and break someone.
- Stripping `Cadl` alone still leaves lots of `Rest.*`. Maybe the namespaces to filter should be bigger and/or configurable, or maybe we should filter all namespaces unless there's a collision?
- It's not really possible to use friendlyName with more than one type parameter. How do you refer to more than one name?
- We report duplicate type names but only on the occurrences after the initial occurence. We should report all occurences as we do for symbols and endpoints. We should also consider along above lines if we can make collisions less likely or impossible in certain cases where they can occur today.
Contributor guide
Assessment
This issue has not been assessed yet.