Skip to content

Files

Latest commit

e881658 · Sep 6, 2023

History

History
This branch is 1732 commits behind microsoft/typespec:main.

openapi3

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
Aug 7, 2023
Sep 6, 2023
Sep 6, 2023
Jan 28, 2022
Feb 16, 2023
Jul 18, 2022
Aug 8, 2023
Aug 8, 2023
Aug 27, 2021
Aug 7, 2023
Jul 18, 2022
Aug 10, 2023
Feb 24, 2022

@typespec/openapi3

TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding

Install

npm install @typespec/openapi3

Emitter

Usage

  1. Via the command line
tsp compile . --emit=@typespec/openapi3
  1. Via the config
emit:
  - "@typespec/openapi3"

Emitter options

file-type

Type: "yaml" | "json"

If the content should be serialized as YAML or JSON. Default 'yaml', it not specified infer from the output-file extension

output-file

Type: string

Name of the output file. Output file will interpolate the following values:

  • service-name: Name of the service if multiple
  • version: Version of the service if multiple

Default: {service-name}.{version}.openapi.yaml or .json if file-type is "json"

Example Single service no versioning

  • openapi.yaml

Example Multiple services no versioning

  • openapi.Org1.Service1.yaml
  • openapi.Org1.Service2.yaml

Example Single service with versioning

  • openapi.v1.yaml
  • openapi.v2.yaml

Example Multiple service with versioning

  • openapi.Org1.Service1.v1.yaml
  • openapi.Org1.Service1.v2.yaml
  • openapi.Org1.Service2.v1.0.yaml
  • openapi.Org1.Service2.v1.1.yaml

new-line

Type: "crlf" | "lf"

Set the newline character for emitting files.

omit-unreachable-types

Type: 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-name

Type: "inline-only" | "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.

Decorators

OpenAPI

@oneOf

Specify that oneOf should be used instead of anyOf for that union.

@OpenAPI.oneOf
Target

Union

Parameters

None

@useRef

Specify an external reference that should be used inside of emitting this type.

@OpenAPI.useRef(ref: valueof string)
Target

union Model | ModelProperty

Parameters
Name Type Description
ref valueof scalar string External reference(e.g. "../../common.json#/components/schemas/Foo")