microsoft / microsoft/typespec
Need a design for how client customizations will look in 3p specs
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
### Clear and concise description of the problem
Right now we have a bunch of decorators and functionality that allow you to customize the shape of the client output for a given language emitter for Azure. One of the challenges is often we are opinionated in that library since we enforce Azure standards.
We need to design how this same functionality could work in 3p specs as well as integrate with other 3p emitters that are written outside of Microsoft.
We can start with 3 fairly straight forward decorators that we know at least one 3p spec is using today.
- [@clientName](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-client-generator-core/lib/decorators.tsp#L5-L25) - allows you to override the name of an element in the emitted library.
- [@usage](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-client-generator-core/lib/decorators.tsp#L165-L251) - allows you to override the usage of a model in the emitted library which can affect the shape of the model.
- [@access](https://github.com/Azure/typespec-azure/blob/main/packages/typespec-client-generator-core/lib/decorators.tsp#L253-L413) - allows you to override whether something is part of the public api surface of the emitted library.
One thing we rely on today is the notion of `scope` which is a parameter for all three of these decorators. It allows you to work easily in multi-emit scenarios where you are emitting multiple languages at once.
For instance if I have the following model in my tsp
```tsp
namespace Bar;
model FooRequest {
name: string;
count: int;
}
```
Lets say you are emitting Java and Dotnet and lets say Dotnet doesn't want the `Request` suffix on the model type as it can be confusing with an HttpRequest. However Java is just fine with the original name and wants to keep it as is. Scope combined with @clientName will let you specify exactly this.
```tsp
@@clientName(Bar.FooRequest, "FooContent", "csharp");
```
The are 4 main scenarios we currently cover with scope
- apply to a single emitter : "csharp"
- apply to a set of emitters : "java,csharp"
- apply to all except a single emitter: "~csharp"
- apply to all except a set of emitters: "~java,csharp"
### Checklist
- [X] Follow our [Code of Conduct](https://github.com/microsoft/typespec/blob/main/CODE_OF_CONDUCT.md)
- [X] Read the [docs](https://typespec.io/docs/).
- [X] Check that there isn't already an issue that request the same feature to avoid creating a duplicate.
Contributor guide
Assessment
This issue has not been assessed yet.