close https://github.com/microsoft/typespec/issues/705
---------
Co-authored-by: iscai-msft <43154838+iscai-msft@users.noreply.github.com>
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Progress for #2564
Changes:
- Decided to cut versioning for now. Starlight doesn't support well now
and would be a decent amount of work. Our doc have been quite stable and
this slows down the build significantly.\
The plan is as follow
1. Merge this as a parallel build to the docusaurus website
2. Add blog back
3. Cleanup things (like migrate more things out of fluentui react
components)
4. Switch the website to use this one
5. If we are happy delete docusaurus
fix#3038
This PR updates the `@typespec/openapi3` package to support converting
OpenAPI3 specs to TypeSpec.
## Example usage:
1. `npm install @typespec/openapi3`
2. `npx openapi3-to-tsp compile --output-dir ./tsp-output
/path/to/openapi-yaml-or-json`
## What's supported
- Parse OpenAPI3 specs in yml/json formats (via 3rd party package)
- Generates file namespace based on OpenAPI3 service name
- Populates `@info` decorator with OpenAPI3 service info
- Converts `#/components/schemas` into TypeSpec models/scalars.
- Converts `#/components/parameters` into TypeSpec models/model
properties as appropriate.
- Generates a response model for every operation/statusCode/contentType
combination.
- Operation tags
- Generates TypeSpec operations with routes/Http Method decorators
- Generates docs/extension decorators
- Most schema decorators
- Model inheritance via `allOf`
- Discriminators
## What's not supported (yet)
- auth
- deprecated directive
- combining multiple versions of an OpenAPI3-defined service into a
single TypeSpec project
- converting `#/components/requestBodies` and `#/components/responses`
into models - TypeSpec doesn't seem to generate these and I didn't find
examples in the wild where they were defined _and_ actually used so
deprioritized.
- emitting warnings/FIXMEs for unexpected/unsupported scenarios
- Probably a lot more that I'm still discovering
## Notes
When going through the TypeSpec -> OpenAPI3 -> TypeSpec loop, the
generated TypeSpec is going to be larger than the original. The biggest
contribution towards this is because I'm currently generating a model
for every possible response on every operation.
I can definitely pare this down with some simple heuristics that take
into account what default statusCode/contentTypes are, and extract the
referenced body type directly in the operation's return signature. I can
also eliminate the `@get` decorators, `@route("/")` routes, and likely
use some of the response models provided by TypeSpec.Http.
However - if I'm using this tool to convert from OpenAPI3 to TypeSpec -
I thought it might be preferable to be more explicit in the generated
output so there's no mystery on how things actually get defined. Will be
interested in feedback on this.
## Testing
For tests, I generate TypeSpec files for a number of OpenAPI3 specs.
Most of the OpenAPI3 specs I generated from our TypeSpec samples
packages. Then I'm able to compare the generated TypeSpec to the
corresponding original TypeSpec file. I've also been diffing the
OpenAPI3 specs generated from the original and generated TypeSpec files
<- these are what typically show no changes outside of known unsupported
conversions (e.g. auth).
---------
Co-authored-by: Christopher Radek <Christopher.Radek@microsoft.com>
resolves#2046
[Playround](https://cadlplayground.z22.web.core.windows.net/prs/3022/)
Add the new syntax for object literals using `#{`. For this first
version an object literal can only contain other object literal and
other literals(string, number, boolean))
## Values axioms
1. `alias` always produces a type. If you attempt to alias a value, you
get an error.
2. A string template produces a string template type if all
substitutions are types, and a value if all substitutions are numeric,
boolean, or string values. A mixture of types and values is an error.
3. The string literal syntax always results in a string literal type
4. A string literal type may be passed as a string value when the
signature expects a value. When the signature expects either a string
literal type or a string value, it is passed as a string value.
5. A string template type can be passed as a string value when all its
substitutions are string literal types.
## Breaking change
### Removal of the `ValueType` replacement with `MixedConstraint`
This shouldn't affect anyone as you were only exposed to this if you
digged into the template parameter and looked at the constraint
## Deprecation
## Using a tuple instead of a tuple literal
- ✅ still work
- emit a warning
<img width="1013" alt="image"
src="https://github.com/microsoft/typespec/assets/1031227/ab05359a-5ed9-4a27-a8d1-f40d1e21766f">
- provide a codefix
<img width="312" alt="image"
src="https://github.com/microsoft/typespec/assets/1031227/5ef93bdf-665f-4445-a6b2-62475efe8c16">
## Using a model expression instead of an object literal
This technically didn't work before(different from above where tuple was
used as a value) but allow this will allow us to convert most of our
decorators to use `valueof` without being breaking
## Old decorator marshalling
If a library had a decorator with `valueof` one of those types
`numeric`, `int64`, `uint64`, `integer`, `float`, `decimal`,
`decimal128`, `null` it used to marshall those as JS `number` and
`NullType` for `null`. With the introduction of values we have a new
marshalling logic which will marshall those numeric types as `Numeric`
and the others will remain numbers. `null` will also get marshalled as
`null`.
For now this is an opt-in behavior with a warning on decorators not
opt-in having a parameter with a constraint from the list above.
Example:
```
extern dec multipleOf(target: numeric | Reflection.ModelProperty, value: valueof numeric);
```
Will now emit a deprecated warning because `value` is of type `valueof
string` which would marshall to `Numeric` under the new logic but as
`number` previously.
To opt-in you can add the following to your library
```ts
export const $flags = defineModuleFlags({
decoratorArgMarshalling: "value",
});
```
---------
Co-authored-by: Brian Terlson <brian.terlson@microsoft.com>
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Add xml library following the approved design.
fix#2970
Only minor change was inverting the parmaeters for `@ns(namespace,
prefix` instead of `@namespace(prefix, namespace)` which makes it
clearer with the other overload `@ns(namespace: EnumMember)`
---------
Co-authored-by: Mark Cowlishaw <markcowl@microsoft.com>
Co-authored-by: Brian Terlson <brian.terlson@microsoft.com>
Timothee Guerin
Christopher Radek
Mario Guerra