@typespec/openapi3 0.47.0-dev.8 → 0.47.0-dev.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +74 -70
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,124 +1,128 @@
1
- # TypeSpec OpenAPI 3.0 Emitter
1
+ # @typespec/openapi3
2
2
 
3
- This package provides the [TypeSpec](https://github.com/microsoft/typespec) emitter to produce OpenAPI 3.0 output from TypeSpec source.
3
+ TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding
4
4
 
5
5
  ## Install
6
6
 
7
- In your typespec project root
8
-
9
7
  ```bash
10
8
  npm install @typespec/openapi3
11
9
  ```
12
10
 
13
- ## Emit OpenAPI 3.0 spec
11
+ ## Emitter
12
+
13
+ ### Usage
14
14
 
15
15
  1. Via the command line
16
16
 
17
17
  ```bash
18
- tsp compile . --emit @typespec/openapi3
18
+ tsp compile . --emit=@typespec/openapi3
19
19
  ```
20
20
 
21
21
  2. Via the config
22
22
 
23
- Add the following to the `tspconfig.yaml` file.
24
-
25
23
  ```yaml
26
- emitters:
27
- @typespec/openapi3: true
24
+ emit:
25
+ - "@typespec/openapi3"
28
26
  ```
29
27
 
30
- For configuration [see options](#emitter-options)
28
+ ### Emitter options
31
29
 
32
- ## Use OpenAPI 3.0 specific decorators:
30
+ #### `file-type`
33
31
 
34
- ```typespec
35
- import "@typespec/openapi3";
32
+ **Type:** `"yaml" | "json"`
36
33
 
37
- using OpenAPI;
34
+ If the content should be serialized as YAML or JSON. Default 'yaml', it not specified infer from the `output-file` extension
38
35
 
39
- // Using `using`
40
- @useRef("common.json#/components/schemas/Foo")
41
- model Foo {}
36
+ #### `output-file`
42
37
 
43
- // Using fully qualified names
44
- @OpenAPI.oneOf
45
- union MyUnion {
46
- cat: Cat,
47
- dog: Dog,
48
- }
49
- ```
38
+ **Type:** `string`
50
39
 
51
- ## Decorators
40
+ Name of the output file.
41
+ Output file will interpolate the following values:
52
42
 
53
- - [@useRef](#useref)
54
- - [@oneOf](#oneof)
43
+ - service-name: Name of the service if multiple
44
+ - version: Version of the service if multiple
55
45
 
56
- ### @useRef
46
+ Default: `{service-name}.{version}.openapi.yaml` or `.json` if `file-type` is `"json"`
57
47
 
58
- Syntax:
48
+ Example Single service no versioning
59
49
 
60
- ```
61
- @useRef(urlString)
62
- ```
50
+ - `openapi.yaml`
63
51
 
64
- `@useRef`
52
+ Example Multiple services no versioning
65
53
 
66
- `@useRef` is used to replace the TypeSpec model type in emitter output with a pre-existing named OpenAPI schema.
54
+ - `openapi.Org1.Service1.yaml`
55
+ - `openapi.Org1.Service2.yaml`
67
56
 
68
- ### @oneOf
57
+ Example Single service with versioning
69
58
 
70
- Syntax:
59
+ - `openapi.v1.yaml`
60
+ - `openapi.v2.yaml`
71
61
 
72
- ```
73
- @oneOf()
74
- ```
62
+ Example Multiple service with versioning
75
63
 
76
- `@oneOf`emits `oneOf` keyword for a union type in the resulting OpenAPI 3.0 specification. It indicates that the value of union type can only contain exactly one of the subschemas.
64
+ - `openapi.Org1.Service1.v1.yaml`
65
+ - `openapi.Org1.Service1.v2.yaml`
66
+ - `openapi.Org1.Service2.v1.0.yaml`
67
+ - `openapi.Org1.Service2.v1.1.yaml`
77
68
 
78
- `@oneOf` can only be applied to a union types.
69
+ #### `new-line`
79
70
 
80
- ## Emitter options:
71
+ **Type:** `"crlf" | "lf"`
81
72
 
82
- Emitter options can be configured via the `tspconfig.yaml` configuration:
73
+ Set the newline character for emitting files.
83
74
 
84
- ```yaml
85
- emitters:
86
- '@typespec/openapi3':
87
- <optionName>: <value>
75
+ #### `omit-unreachable-types`
88
76
 
77
+ **Type:** `boolean`
89
78
 
90
- # For example
91
- emitters:
92
- '@typespec/openapi3':
93
- outputFile: my-custom-openapi.json
94
- ```
79
+ Omit unreachable types.
80
+ 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.
95
81
 
96
- or via the command line with
82
+ #### `include-x-typespec-name`
97
83
 
98
- ```bash
99
- --option "@typespec/openapi3.<optionName>=<value>"
84
+ **Type:** `"inline-only" | "never"`
100
85
 
101
- # For example
102
- --option "@typespec/openapi3.output-file=my-custom-openapi.json"
86
+ If the generated openapi types should have the `x-typespec-name` extension set with the name of the TypeSpec type that created it.
87
+ This extension is meant for debugging and should not be depended on.
88
+
89
+ ## Decorators
90
+
91
+ ### OpenAPI
92
+
93
+ - [`@oneOf`](#@oneof)
94
+ - [`@useRef`](#@useref)
95
+
96
+ #### `@oneOf`
97
+
98
+ Specify that `oneOf` should be used instead of `anyOf` for that union.
99
+
100
+ ```typespec
101
+ @OpenAPI.oneOf
103
102
  ```
104
103
 
105
- ### `output-file`
104
+ ##### Target
105
+
106
+ `Union`
106
107
 
107
- Configure the name of the swagger output file relative to the compiler `output-path`.
108
+ ##### Parameters
108
109
 
109
- ### `new-line`
110
+ None
110
111
 
111
- Set the newline character for emitting files. Can be either:
112
+ #### `@useRef`
112
113
 
113
- - `lf`(Default)
114
- - `crlf`
114
+ Specify an external reference that should be used inside of emitting this type.
115
+
116
+ ```typespec
117
+ @OpenAPI.useRef(ref: valueof string)
118
+ ```
115
119
 
116
- ### `omit-unreachable-types`
120
+ ##### Target
117
121
 
118
- Only include types referenced via an operation.
122
+ `union Model | ModelProperty`
119
123
 
120
- ## See also
124
+ ##### Parameters
121
125
 
122
- - [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
123
- - [TypeSpec Website](https://microsoft.github.io/typespec)
124
- - [TypeSpec for the OpenAPI Developer](https://github.com/microsoft/typespec/blob/main/docs/typespec-for-openapi-dev.md)
126
+ | Name | Type | Description |
127
+ | ---- | ----------------------- | -------------------------------------------------------------------- |
128
+ | ref | `valueof scalar string` | External reference(e.g. "../../common.json#/components/schemas/Foo") |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@typespec/openapi3",
3
- "version": "0.47.0-dev.8",
3
+ "version": "0.47.0-dev.9",
4
4
  "author": "Microsoft Corporation",
5
5
  "description": "TypeSpec library for emitting OpenAPI 3.0 from the TypeSpec REST protocol binding",
6
6
  "homepage": "https://microsoft.github.io/typespec",