OpenAPI3 to TypeSpec
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.
Usage
- via the command line
tsp-openapi3 ./openapi3spec.yml --output-dir ./tsp-output
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
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
This example demonstrates how to convert component schemas from OpenAPI3 to TypeSpec.
OpenAPI3
components: schemas: Product: type: object required: - id - name properties: id: type: string name: type: string price: type: number format: float
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
This example demonstrates how to convert component parameters from OpenAPI3 to TypeSpec.
OpenAPI3
components: parameters: ProductId: name: id in: path required: true schema: type: string
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
This example demonstrates how to convert path routes from OpenAPI3 to TypeSpec operations.
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
/** * 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
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
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 |
|
|