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 [--namespace MyNamespace]

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.
namespace	string	optional	The namespace to use for the generated TypeSpec files. Defaults to a sanitized version of the description info title if not provided.

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

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

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

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;
}

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

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;