Skip to content

OpenAPI3 to TypeSpec

This package includes the tsp-openapi3 CLI for converting OpenAPI 3 specs into TypeSpec. The generated TypeSpec depends on the @typespec/http, @typespec/openapi and @typespec/openapi3 libraries.

  1. via the command line
Terminal window
tsp-openapi3 ./openapi3spec.yml --output-dir ./tsp-output

The path to the OpenAPI3 yaml or json file must be passed as a position argument.

The named arguments are:

NameTypeRequiredDescription
output-dirstringrequiredThe output directory for generated TypeSpec files. Will be created if it does not exist.
helpbooleanoptionalShow help.

All schemas present at #/components/schemas will be converted into a model or scalar as appropriate.

OpenAPI3 TypeSpec
components:
schemas:
Widget:
type: object
required:
- id
- weight
- color
properties:
id:
type: string
weight:
type: integer
format: int32
color:
type: string
enum:
- red
- blue
uuid:
type: string
format: uuid
model Widget {
id: string;
weight: int32;
color: "red" | "blue";
}
@format("uuid")
scalar uuid extends string;

Detailed Example for Converting Component Schemas

Section titled “Detailed Example for Converting Component Schemas”

This example demonstrates how to convert component schemas from OpenAPI3 to TypeSpec.

components:
schemas:
Product:
type: object
required:
- id
- name
properties:
id:
type: string
name:
type: string
price:
type: number
format: float
model Product {
id: string;
name: string;
price: float;
}

In this example, the Product schema from OpenAPI3 is converted into a TypeSpec model.

Detailed Example for Converting Component Parameters

Section titled “Detailed Example for Converting Component Parameters”

This example demonstrates how to convert component parameters from OpenAPI3 to TypeSpec.

components:
parameters:
ProductId:
name: id
in: path
required: true
schema:
type: string
model Product {
@path id: string;
}

In this example, the ProductId parameter from OpenAPI3 is converted into a TypeSpec model with a @path decorator.

Detailed Example for Converting Path Routes to Operations

Section titled “Detailed Example for Converting Path Routes to Operations”

This example demonstrates how to convert path routes from OpenAPI3 to TypeSpec operations.

paths:
/products/{id}:
get:
operationId: getProduct
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/Product"
/**
* Successful response
*/
model getProduct200ApplicationJsonResponse {
@statusCode statusCode: 200;
@bodyRoot body: Product;
}
@route("/products/{id}") @get op getProduct(@path id: string): getProduct200ApplicationJsonResponse;

In this example, the getProduct path route from OpenAPI3 is converted into a TypeSpec operation with a response model.

2. Convert component parameters into models or fields

Section titled “2. Convert component parameters into models or fields”

All parameters present at #/components/parameters will be converted to a field in a model. If the model doesn’t exist in #/components/schemas, then it will be created.

OpenAPI3 TypeSpec
components:
parameters:
Widget.id:
name: id
in: path
required: true
schema:
type: string
schemas:
Widget:
type: object
required:
- id
- weight
- color
properties:
id:
type: string
weight:
type: integer
format: int32
color:
type: string
enum:
- red
- blue
model Widget {
@path id: string;
weight: int32;
color: "red" | "blue";
}
components:
parameters:
Foo.id:
name: id
in: path
required: true
schema:
type: string
model Foo {
@path id: string;
}

All routes using one of the HTTP methods supported by @typespec/http will be converted into operations at the file namespace level. A model is also generated for each operation response.

At this time, no automatic operation grouping under interfaces is performed.

OpenAPI3 TypeSpec
paths:
/{id}:
get:
operationId: readWidget
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The request has succeeded.
content:
application/json:
schema:
$ref: "#/components/schemas/Widget"
/**
* The request has succeeded.
*/
model readWidget200ApplicationJsonResponse {
@statusCode statusCode: 200;
@bodyRoot body: Widget;
}
@route("/{id}") @get op readWidget(@path id: string): readWidget200ApplicationJsonResponse;