OpenAPI3 to TypeSpec
Converting OpenAPI 3 into TypeSpec
Section titled “Converting OpenAPI 3 into 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.
- via the command line
tsp-openapi3 ./openapi3spec.yml --output-dir ./tsp-output
tsp-openapi3 arguments
Section titled “tsp-openapi3 arguments”The path to the OpenAPI3 yaml or json file must be passed as a position argument.
The named arguments are:
Name | Type | Required | Description |
---|---|---|---|
output-dir | string | required | The output directory for generated TypeSpec files. Will be created if it does not exist. |
help | boolean | optional | Show help. |
Examples
Section titled “Examples”1. Convert component schemas into models
Section titled “1. Convert component schemas into models”All schemas present at #/components/schemas
will be converted into a model or scalar as appropriate.
OpenAPI3 | TypeSpec |
|
|
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.
OpenAPI3
Section titled “OpenAPI3”components: schemas: Product: type: object required: - id - name properties: id: type: string name: type: string price: type: number format: float
TypeSpec
Section titled “TypeSpec”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.
OpenAPI3
Section titled “OpenAPI3”components: parameters: ProductId: name: id in: path required: true schema: type: string
TypeSpec
Section titled “TypeSpec”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.
OpenAPI3
Section titled “OpenAPI3”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"
TypeSpec
Section titled “TypeSpec”/** * 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 |
|
|
|
|
3. Convert path routes to operations
Section titled “3. Convert path routes to operations”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 |
|
|