package
TypeSpec library for emitting OpenAPI 3.0 and OpenAPI 3.1 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec
npm install @typespec/openapi3GitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
Tagged topics.
Latest published Nov 11, 2026
next
latest
microsoft1es
npmjs@microsoft.com
Estimated unpacked size across 17 packages.
14.4 MB
Includes dependencies.
6 direct · 2 outdated
^2.9.0
2.9.1
^0.25.0
0.28.1
^0.17.0
0.19.1
^0.9.8
0.9.9
^0.29.16
0.29.22
^0.79.3
0.79.3
TypeSpec library for emitting OpenAPI 3.0 and OpenAPI 3.1 from the TypeSpec REST protocol binding and converting OpenAPI3 to TypeSpec
npm install @typespec/openapi3tsp compile . --emit=@typespec/openapi3emit:
- "@typespec/openapi3"The config can be extended with options as follows:
emit:
- "@typespec/openapi3"
options:
"@typespec/openapi3"
emitter-output-dirType: absolutePath
Defines the emitter output directory. Defaults to {output-dir}/@typespec/openapi3
See Configuring output directory for more info
file-typeType: "yaml" | "json" | ("yaml" | "json")[]
If the content should be serialized as YAML or JSON. Can be a single value or an array to emit multiple formats. Default 'yaml', if not specified infer from the output-file extension
Options:
"yaml" | "json"("yaml" | "json")[]output-fileType: string
Name of the output file. Output file will interpolate the following values:
file-type is an array.Default: {service-name-if-multiple}.{version}.openapi.yaml or .json if file-type is "json"
When file-type is an array: {service-name-if-multiple}.{version}.openapi.{file-type}
Example Single service no versioning
openapi.yamlExample Multiple services no versioning
openapi.Org1.Service1.yamlopenapi.Org1.Service2.yamlExample Single service with versioning
openapi.v1.yamlopenapi.v2.yamlExample Multiple service with versioning
openapi.Org1.Service1.v1.yamlopenapi.Org1.Service1.v2.yamlopenapi.Org1.Service2.v1.0.yamlopenapi.Org1.Service2.v1.1.yamlopenapi-versionsType: "3.0.0" | "3.1.0" | "3.2.0"
Default: ["3.0.0"]
new-lineType: "crlf" | "lf"
Default: "lf"
Set the newline character for emitting files.
omit-unreachable-typesType: boolean
Omit unreachable types. By default all types declared under the service namespace will be included. With this flag on only types references in an operation will be emitted.
include-x-typespec-nameType: "inline-only" | "never"
Default: "never"
If the generated openapi types should have the x-typespec-name extension set with the name of the TypeSpec type that created it.
This extension is meant for debugging and should not be depended on.
safeint-strategyType: "double-int" | "int64"
Default: "int64"
How to handle safeint type. Options are:
double-int: Will produce type: integer, format: double-intint64: Will produce type: integer, format: int64Default: int64
seal-object-schemasType: boolean
Default: false
If true, then for models emitted as object schemas we default additionalProperties to false for
OpenAPI 3.0, and unevaluatedProperties to false for OpenAPI 3.1, if not explicitly specified elsewhere.
Default: false
experimental-parameter-examplesType: "data" | "serialized"
Determines how to emit examples on parameters. Note: This is an experimental feature and may change in future versions. See https://spec.openapis.org/oas/v3.0.4.html#style-examples for parameter example serialization rules See https://github.com/OAI/OpenAPI-Specification/discussions/4622 for discussion on handling parameter examples.
operation-id-strategyType: "parent-container" | "fqn" | "explicit-only" | object { kind, separator }
Options:
"parent-container" | "fqn" | "explicit-only" (default: "parent-container")
Determines how to generate operation IDs when @operationId is not used.
Avaliable options are:
parent-container: Uses the parent namespace and operation name to generate the ID.
fqn: Uses the fully qualified name of the operation to generate the ID.
explicit-only: Only use explicitly defined operation IDs.
object { kind, separator }
| Name | Type | Default | Description |
|---|---|---|---|
kind | "parent-container" | "fqn" | "explicit-only" | "parent-container" | Determines how to generate operation IDs when @operationId is not used.Avaliable options are: - parent-container: Uses the parent namespace and operation name to generate the ID.- fqn: Uses the fully qualified name of the operation to generate the ID.- explicit-only: Only use explicitly defined operation IDs. |
separator | string | Separator used to join segment in the operation name. |
enum-strategyType: "default" | "annotated"
Default: "default"
How to emit TypeSpec enums and unions of literals. Options are:
default: Emit as a single schema using the enum keyword.annotated: Emit as a oneOf of const subschemas annotated with title and description
from each member's/variant's @summary and @doc. Follows the OpenAPI 3.1.1 annotated enumerations pattern.
Only supported by OpenAPI 3.1.0 and above; on 3.0.0 the default style is used and a warning is reported.@oneOfSpecify that oneOf should be used instead of anyOf for that union.
@TypeSpec.OpenAPI.oneOfUnion | ModelProperty
None
@useRefSpecify an external reference that should be used inside of emitting this type.
@TypeSpec.OpenAPI.useRef(ref: valueof string)Model | ModelProperty
| Name | Type | Description |
|---|---|---|
| ref | valueof string | External reference(e.g. "../../common.json#/components/schemas/Foo") |