---
title: TypeSpec For OpenAPI Developer
---
# TypeSpec for the OpenAPI developer
This guide is an introduction to TypeSpec using concepts that will be familiar to developers
that either build or use API definitions in OpenAPI v2 or v3.
In many case, this will also describe how the typespec-autorest and openapi3 emitters translate
TypeSpec designs into OpenAPI.
The document is organized around the features of an OpenAPI v2 or v3 definition.
The idea is that if you know how to describe some API feature in OpenAPI, you can just navigate
to the section of this document for that feature.
## Data Types
In OpenAPI [v2](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#data-types)/[v3](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#dataTypes), data types are specified using the `type` and `format` fields in a schema.
The TypeSpec equivalent of OpenAPI data types are the TypeSpec primitive types or [built-in models](https://microsoft.github.io/typespec/docs/standard-library/built-in-types).
The following table shows how common OpenAPI types map to TypeSpec types:
| OpenAPI `type`/`format` | TypeSpec type | Notes |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------- |
| `type: integer, format: int32` | `int32` | |
| `type: integer, format: int64` | `int64` | |
| `type: number, format: float` | `float32` | |
| `type: number, format: double` | `float64` | |
| `type: string` | `string` | |
| `type: string, format: byte` | `bytes` | for content-type == 'application/json' or 'text/plain' |
| `type: string, format: binary` | `bytes` | for "binary" content types, e.g. 'application/octet-stream', 'image/jpeg' |
| `type: boolean` | `boolean` | |
| `type: string, format: date` | `plainDate` | |
| `type: string, format: date-time` | `zonedDateTime` | RFC 3339 date |
| `type: string, format: password` | `@secret string` | |
OpenAPI supports a variety of "assertions" that can be used further restrict the values allowed for a data type.
These are actually borrowed into OpenAPI from JSON Schema.
For `type: integer` and `type: number` data types:
| OpenAPI/JSON Schema keyword | TypeSpec construct | Notes |
| --------------------------- | ---------------------------- | ----- |
| `minimum: value` | `@minValue(value)` decorator | |
| `maximum: value` | `@maxValue(value)` decorator | |
For `type: string` data types:
| OpenAPI/JSON Schema keyword | TypeSpec construct | Notes |
| --------------------------- | ----------------------------- | ----- |
| `minLength: value` | `@minLength(value)` decorator | |
| `maxLength: value` | `@maxLength(value)` decorator | |
| `pattern: regex` | `@pattern(regex)` decorator | |
There are two ways to define an `enum` data type. One is with the [TypeSpec `enum` statement](https://microsoft.github.io/typespec/docs/language-basics/enums), e.g.:
```typespec
enum Color {
Red: "red",
Blue: "blue",
Green: "green",
}
```
Another is to use the union operation to define the enum values inline, e.g.:
```typespec
status: "Running" | "Stopped" | "Failed"
```
## Host / BasePath / Servers
In OpenAPI v2, the `host` and `basePath` fields at the top-level of the API definition combine to form the base URL for the API. The paths defined in the `paths` object are appended to this base URL to form the absolute URL for an operation.
In OpenAPI v3, the top-level `servers` field specifies an array of `server` objects [[v3][v3-server]] with a base URL, which may be parameterized, to which the operation path can be appended.
[v3-server]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#server-object
There is also an autorest extension used in many Azure API definitions called [`x-ms-parameterized-host`](https://github.com/Azure/autorest/tree/main/docs/extensions#x-ms-parameterized-host) to define the base URL for the service.
In TypeSpec, the `host` in OpenAPI v2 can be specified with the `@server` decorator on the namespace(From `@typespec/rest` library). Similar support will be added to the openapi3 emitter shortly.
## Paths Object
In OpenAPI, the `paths` object [[v2][v2-paths], [v3][v3-paths]] is the top-level structure for defining the operations of the API, organized with the "path" for the operation.
[v2-paths]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#paths-object
[v3-paths]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#paths-object
In TypeSpec, a path is associated with a `namespace` using the `@route` decorator. Then all operations within the namespace use this path, plus any path parameters an operation may define.
```typespec
@route("/pets")
namespace Pets {
op create(@body pet: Pet): Pet; // uses path "/pets"
op read(@path petId: int32): Pet; // uses path "/pets/{petId}"
}
```
## Path Item Object
In OpenAPI, a path item object [[v2][v2-pathitem], [v3][v3-pathitem]] describes the operations available on a single path. A path may have at most one `get`, `put`, `post`, `patch`, `delete`, or `head` operation.
[v2-pathitem]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#pathItemObject
[v3-pathitem]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#pathItemObject
In TypeSpec, operations are defined within a namespace with a syntax very similar to typescript functions.
The http method for an operation can be specified explicitly using a decorator: `@get`, `@put`, `@post`, `@patch`, `@delete`, or `@head`.
But a namespace may contain operations for a set of related paths (depending on path parameters), and so may have multiple operations that use a particular HTTP method.
The http method decorators also accept an explicit path, which is appended to the namespace path.
```typespec
@route("/pets")
namespace Pets {
@get op list(): Pet[]; // get on path "/pets"
@get op read(@path petId: int32): Pet; // get on path "/pets/{petId}"
@post
@route("{petId}:walk")
op walk(... PetId): ; // post on path "/pets/{petId}:walk"
}
```
## Operation Object
In OpenAPI, an operation object [[v2][v2-operation], [v3][v3-operation]] describes an operation.
[v2-operation]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#operationObject
[v3-operation]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#operationObject
The fields in an OpenAPI operation object are specified with the following TypeSpec constructs:
| OpenAPI `operation` field | TypeSpec construct | Notes |
| ------------------------- | ------------------------ | ----------------------------------------- |
| `description` | `@doc` decorator | |
| `operationId` | `@operationId` decorator | |
| `parameters` | `op` parameter list | see [Parameter Object](#parameter-object) |
| `responses` | `op` return type(s) | see [Responses Object](#responses-object) |
| `tags` | `@tag` decorator | |
| `consumes` | `@header contentType` | as a union (enum) of the MIME types |
| `produces` | `@header accept` | as a union (enum) of the MIME types |
| `summary` | | Not currently supported. |
| `security` | | Not currently supported. |
## Parameter Object
In OpenAPI, a parameter object [[v2][v2-parameter], [v3][v3-parameter]] describes a single operation parameter.
[v2-parameter]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#parameter-object
[v3-parameter]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#parameterObject
The fields of a parameter object correspond to the following TypeSpec constructs:
<!-- prettier-ignore-start -->
| OpenAPI `parameter` field | TypeSpec construct | Notes |
| ------------------------- | ---------------- | ------------------------------------- |
| `name` | parameter name | |
| `in` | decorator | `@query`, `@path`, `@header`, `@body` |
| `type` | parameter type | see [Data Types](#data-types) |
| `description` | `@doc` decorator | |
| `required` | from parameter "optionality" | a "?" following the parameter name indicates it is optional (`required: false`), otherwise it is required (`required: true`) |
| `deprecated` | | Not currently supported. |
| `allowEmptyValue` | | Not currently supported. |
| `collectionFormat` | | Not currently supported. |
<!-- prettier-ignore-end -->
## RequestBody Object (OAS3)
In OpenAPI v3, the operation request body is defined with a `requestBody` object rather than as a parameter.
An OpenAPI v3 `requestBody` corresponds to a TypeSpec `op` parameter with the `@body` decorator.
## Responses Object
In OpenAPI, the responses object [[v2][v2-responses], [v3][v3-responses]] specifies the possible responses for an operation.
The responses object maps a HTTP response code to the expected response.
[v2-responses]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responsesObject
[v3-responses]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#responsesObject
In TypeSpec, operation responses are defined by the return types of the `op`. The status code for a response can be specified as a property in the return type with the `@statusCode` decorator (the property name is ignored). The TypeSpec.Http package also defines several standard response types:
| OpenAPI response | TypeSpec construct |
| ---------------- | ---------------------- |
| `200` | `OkResponse` |
| `201` | `CreatedResponse` |
| `202` | `AcceptedResponse` |
| `204` | `NoContentResponse` |
| `301` | `MovedResponse` |
| `304` | `NotModifiedResponse` |
| `401` | `UnauthorizedResponse` |
| `404` | `NotFoundResponse` |
| `409` | `ConflictResponse` |
If a return type does not contain a `statusCode`, it is assumed to be the `200` response.
### Response Object
In OpenAPI, a response object [[v2][v2-response], [v3][v3-response]] describes a single response for an operation.
The structure of the response object changed significantly from OpenAPI v2 to OpenAPI v3, but there are many
elements common to both.
[v2-response]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#responseObject
[v3-response]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#responseObject
The fields in an OpenAPI response object are specified with the following TypeSpec constructs:
| OpenAPI `response` field | TypeSpec construct | Notes |
| ------------------------ | -------------------------------------------------- | ------------------------ |
| `description` | `@doc` decorator | |
| `schema` | return type | |
| `headers` | fields in the return type with `@header` decorator | |
| `examples` | | Not currently supported. |
| `links` (OAS3) | | Not currently supported. |
## Schema Object
OpenAPI schemas are represented in TypeSpec by [models](https://microsoft.github.io/typespec/docs/language-basics/models/).
Models have any number of members and can extend and be composed with other models.
Models can be defined with the `model` statement and then referenced by name, which generally results in a `$ref` to a schema for the model in the `definitions` or `components.schemas` section of the OpenAPI document.
TypeSpec supports the ["spread" operator](https://microsoft.github.io/typespec/docs/language-basics/models/#spread) (`...`), which copies the members of the source model into the target model.
But TypeSpec processes all spread transformations before emitters are invoked, so this form of reuse is not represented in the emitted OpenAPI.
The spread operation is useful if you want one or more properties to be present in several different models but in a standard fashion. For example:
```typespec
model Legs {
@doc("number of legs") legs: int32;
}
model Dog {
name: string;
...Legs;
}
model Cat {
name: string;
...Legs;
}
model Snake {
name: string;
// snakes have no legs
}
```
TypeSpec also supports single inheritance of models with the `extends` keyword. This construct can be used to produce an `allOf` with a single element (the parent schema) in OpenAPI. For example:
```typespec
model Pet {
name: string;
}
model Cat extends Pet {
meow: int32;
}
model Dog extends Pet {
bark: string;
}
```
TypeSpec does not current provide a means to produce an `allOf` with more than one element -- these are generally treated as "composition" in code generators and thus better represented in TypeSpec with the spread operator.
TypeSpec does not yet support a means to specify an OpenAPI `discriminator` but this support is currently in development.
## definitions / components
OpenAPI supports reuse of schemas, parameters, responses, and other elements with the `definitions` (OAS2) or `components` (OAS3) section of an OpenAPI definition.
Referencing a model by name (not with "spread"), as an `op` parameter or return type or as the type of a property in another model, generally results in a `$ref` to a schema for the model in the `definitions` or `components.schemas` section of the OpenAPI document.
Reusable parameters can be defined as members of a model and then incorporated into an operation parameter list using the spread operator. For example:
```typespec
model PetId {
@path petId: int32;
}
namespace Pets {
op read(...PetId): Pet | Error;
}
```
results in a `$ref` to the named parameter `PetId` in either `parameters` or `components.parameters`.
## Info Object
In OpenAPI, the `info` object [[v2][v2-info], [v3][v3-info]] contains metadata about the API such as a `title`, `description`, `license`, and `version`.
[v2-info]: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#infoObject
[v3-info]: https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#infoObject
In TypeSpec this information is specified with [decorators on the namespace][typespec-service-metadata].
| OpenAPI `info` field | TypeSpec decorator | Notes |
| -------------------- | ---------------------- | ------------------------ |
| `title` | `@service({title: }` | TypeSpec built-in decorator |
| `version` | `@service({version: }` | TypeSpec built-in decorator |
| `description` | `@doc` | TypeSpec built-in decorator |
| `license` | | Not currently supported. |
| `contact` | | Not currently supported. |
[typespec-service-metadata]: https://microsoft.github.io/typespec/docs/standard-library/http/#service-definition-and-metadata
## Consumes / Produces (OAS2)
In OpenAPI v2, the top-level `consumes` and `produces` fields specify a list of MIME types an operation can consume / produce
when not overridden by a `consumes` or `produces` on an individual operation.
The typespec-autorest emitter previously supported `@produces` and `@consumes` decorators on a namespace, but these are deprecated
in favor of explicit `content-type` and `accept` header properties in request and response bodies.
## securityDefinitions / securitySchemes Object
Use `@useAuth` decorator from the `@typespec/rest" library
```typespec
using TypeSpec.Http;
@useAuth(OAuth2Auth<["read", "write"]>)
namespace MyService;
```
## Specification Extensions
You can add arbitrary specification extensions ("x-" properties) to a model or an operation with the `@extension` decorator.
For example:
```typespec
namespace Pets {
@extension("x-streaming-operation", true) op read(...PetId): Pet | Error;
}
```microsoft/typespec
Publicmirrored fromhttps://github.com/microsoft/typespecAvailable
docs/getting-started/cadl-for-openapi-dev.md
338lines · modepreview