August 2022
Release Notes August 2022 (2022-08-10)
This release contains breaking changes
- typespec-azure-core library requires a versioned dependency
- typespec-azure-resource-manager requires a versioned dependency
- Operation parameters without decorators
- OkResponse is no longer a template
- Route resolution changes
- Remove
Map
type @path
may not decorate optional properties or parameters without a default value
typespec-azure-core library requires a versioned dependency
The typespec-azure-core library is now versioned, so each spec using it must specify the version to ensure no breaking changes.
Unversioned dependency to typespec-azure-core will now emit an error
Resolve by adding an @versionedDependency
to typespec-azure-core to the service namespace
typespec-azure-resource-manager library requires a versioned dependency
The typespec-azure-resource-manager library is now versioned, so each spec using it must specify the version to ensure no breaking changes.
Unversioned dependency to typespec-azure-resource-manager will now emit an error
Resolve by adding an @versionedDependency
to typespec-azure-resource-manager to the service namespace
Operation parameters without decorators
A single undecorated (not marked @query
, @header
, @body
or @path
) operation parameter will now become a property of the request body rather than have its type define the request body. This allows defining the body with multiple unannotated parameters, which can include unannotated properties that are spread into parameters. (Previously, more than one unannotated parameter was an error.)
For example, the following used to define a request body of type string
, but now defines a request body that is an object with a property named body
of type string.
To get the previous behavior, the parameter now needs to be explicitly marked with @body
:
OkResponse is no longer a template
Previously, OkResponse took an argument for the body type. Now it is a simple model like the other XxxResponse types. Alone, it implies a status code of 200 with no body.
Since 200 is the default status code for non-empty bodies, you can usually replace OkResponse<T>
with simply T
.
Can be:
In certain situations where the body type is not (necessarily) a model, you will need to use the new Body<T>
type. For example.
Can become:
Since 200 status code is used by default, this could also be:
Generic models based on OkResponse<T>
may also require Body<T>
. For example:
Since T is not constrainted to be a model, it might be an intrinsic type, an array, or the like, the template should be changed to use Body<T>
:
In general, the prior OkResponse<T>
is equivalent to OkResponse & Body<T>
now or, equivalently, { ...OkResponse, ...Body<T> }
. In practice there are many situations where you can leave out OkResponse altogether and use plain T
rather than Body<T>
.
See also https://github.com/microsoft/typespec/blob/main/docs/tutorial.md#request—response-bodies
Route resolution changes
Resolving operation routes now follows the following logic:
- if there is a service namespace specified
- only emit the operations and interfaces under that namespace(recursively)
- if not:
- only emit the operations and interfaces defined at the root (DO NOT look into namespaces)
Action if applicable
- If a typespec specused a service namespace without
@serviceTitle
add the@serviceTitle
decorator to the service namespace, otherwise no routes will be emitted. - If a typespec spec contains service namespaces that are not child namespaces of the service namespace, move these namespaces under the service namespace.
Cases
Operation at the root
âś… Stay the same
Before | After |
---|---|
["/"] | ["/"] |
Operation in namespace (not service namespace)
⚠️ Output stays the same but add warning that no routes are emitted
Before | After |
---|---|
[] | [] |
Operation in namespace (not service namespace) with @route
⚠️ Now the same as previous case, no routes emitted and emit warning
Before | After |
---|---|
["/"] | [] |
Resolve by adding the @serviceTitle
decorator
Add @serviceTitle
to the namespace
Operation in service namespace
âś… Stay the same
Before | After |
---|---|
["/"] | ["/"] |
Operation in namespaces other than the service namespace
⚠️ Other namespace routes are not included anymore
Before | After |
---|---|
["/in-service", "my-lib"] | ["/in-service"] |
Resolve by making additional namespaces children of the service namespace
Make any added namespaces children of the service namespace
Remove Map type
Map
type was removed. Usages of Map<string, T>
can be replaced with new type Record<T>
. Other usages of Map
may be replaced with object
.
Map using string key type
Replace with Record<T>
Map using non-string key type
Replace with object
@path
may not decorate optional properties or parameters without a default
Properties and parameters marked with the @path
decorator should be required, but may be optional if they have a default value
optional path parameters
Was a bad practice, but was allowed in previous versions. This will not throw an error diagnostic.