Examples of using TypeSpec to create OpenAPI v3 API definitions

This project is a companion to the TypeSpec for the OpenAPI developer documentation.

Here we will show playgound examples of the features that are described in the documentation.

Data Types

type and format

The data types playground shows how common OpenAPI types map to TypeSpec types.

Schema assertions

The assertions playground shows how to specify various schema assertions in TypeSpec.

enum

The enum playground shows how tospecify an enum in TypeSpec using either the enum keyword or with union types.

defaults

The defaults playground shows how to specify a default value for a property in TypeSpec.

Info / Servers

The info-and-servers playground shows how to specify the elements of the info object and servers object in TypeSpec.

Paths Object

The paths playground shows how to specify the path for an operation with the @route decorator on namespaces and operations and the @path decorator on parameters.

Path Item Object

The pathitems playground shows how to produce path items with the @get, @put, @post, @patch, @delete, or @head decorators on operations.

If an HTTP method decorator is not specified then the default is post if there is a body and get otherwise.

Other path item fields are not currently supported.

Operation Object

tag

The tags playground shows how to add tags to an operation object with the @tag decorator on a namespace or operation.

description and summary

The operation docs playground shows how to specify the description for an operation using the @doc decorator or a doc comment. It also illustrates the @summary decorator to specify an operation summary.

externalDocs

The external docs playground shows how to specify externalDocs for an operation with the OpenAPI libray @externalDocs decorator.

operationId

The operationId playground shows how the operationId for an operation is derived from the operation name and interface/namespace, and how to specify the operationId explicitly using the @operationId decorator.

Parameters / Parameter Object

The parameters playground shows how the parameters of a TypeSpec operation are converted to operation parameters in OpenAPI.

It illustrates the use of the @query, @path, and @header decorators to specify the in field of the OpenAPI parameter object.

style and explode

TypeSpec provides a format parameter on the @query or @header decorators to specify the style and explode fields of the OpenAPI parameter object. format is required if the parameter value is an array but optional otherwise.

The style and explode playground illustrates the following rules for the style and explode fields:

Query parameters
- format unspecified: style and explode are not set, so the OpenAPI defaults are used.
- format: "form": parameter has style: form and explode: true (the OpenAPI default)
- format: "csv": parameter should have style: form and explode: false (issue #2234)
- format: "ssv": parameter has style: spaceDelimited and explode: false
- format: "pipes": parameter has style: pipeDelimited and explode: false
Header parameters
- format unspecified: style and explode are not set, so the OpenAPI defaults are used.
- format: "simple": parameter has style: simple and no explode (the OpenAPI default)

Thr style and explode playground illustrates the above rules.

Request Body Object

The request body playground shows how to specify the request body for an operation in TypeSpec.

The request body can be specified explicity, with the @body decorator, or implicitly.
By default, the media-type is "application/json", but one or more media-types can be specified with a content-type header.
Use the @sharedRoute decorator to specify multiple media-types with different schemas.

multipart/form-data

The multipart/form-data playground shows how to specify a multipart/form-data request body in TypeSpec.

When using multipart/form-data to upload a file, use the @format("binary") decorator on the file property so that the implied content-type is "application/octet-stream".

The multipart/form-data with array of files playground shows how to specify a multipart/form-data request body in TypeSpec with an array of files.

You can't specify @format("binary") on an array property, so you need to define a scalar to represent a file with @format("binary") and then define a body property as an array of this scalar type.

Responses

The responses object in OpenAPI is a map of status codes to response objects.

The responses playground shows how to specify the status codes for operation responses in TypeSpec.

Specify the status code for a response with the @statusCode decorator.
The default status code is "200" unless the response is void in which case the default is "204".
A "default" response can be specified with the @error decorator.
The TypeSpec.Http package defines many standard response types, which can be used on their own or intersected with a model to define the response body.
Use @minValue and @maxValue to specify a response code range such as "4XX" or "5XX".

Response Object

The response object playground shows how to specify operation responses in TypeSpec.

By default, the media-type of the response is "application/json", but one or more media-types can be specified explicitly with a content-type header.
To get multiple content entries with different schemas, use a union type.
Use @doc on the return type, or @returns and @error in the operation description, to set the response description.
Specify headers in the response object with properties in the return type with the @header decorator.

Currently you cannot specify examples or links for a response object in TypeSpec.

Schema Object

This section extends the information from the Data Types section with some advanced features of the OpenAPI schema object.

additionalProperties

The additionalProperties playground shows how to specify a schema with additionalProperties in TypeSpec using the Record type.

allOf

The allOf playground shows how to specify a schema with allOf in TypeSpec using the extends keyword.

discriminator

The discriminator playground shows how to specify a schema with discriminator in TypeSpec using the @discriminator decorator.

This schema produced for the base model will be defined with a discriminator property and schemas for the child models will allOf the base schema and add additional properties.

anyOf

The anyOf playground shows how to specify a schema with anyOf in TypeSpec using the union type.

Union types are rendered as anyOf because the union variants might not be mutually exclusive, as required for oneOf. See the next section for how to specify oneOf.

oneOf

The oneOf playground shows how to specify a schema with oneOf in TypeSpec using the @oneOf decorator on a union.

You must import the @typespec/openapi3 package to use the @oneOf decorator.

Another common use of oneOf is to specify that a property can be one of several types, say a string or an integer.

The oneOf basic types playground shows how to produce a oneOf for non-object types using the @oneOf decorator on a "unnamed" union.

oneOf with discriminator

The oneOf with discriminator playground shows how to combine the @oneOf and @discriminator decorators to produce a polymorphic schema with oneOf and discriminator.

nullable

The nullable playground shows how to specify a schema with nullable in TypeSpec.

readOnly

The readOnly playground shows how to specify a schema with readOnly in TypeSpec using @visibility("read").

external $ref

The external ref playground shows how to specify a schema with a $ref to an external schema in TypeSpec using the @useRef decorator.

You must import the @typespec/openapi3 package to use the @useRef decorator.

securityDefinitions / securitySchemes

The security playground shows how to specify security schemes in TypeSpec with the @useAuth decorator.

Specification Extensions

The extensions playground shows how to specify specification extensions to models, properties, operations, and parameters in TypeSpec with the @extension decorator.

richardpark-msft/typespec-openapiv3-examples