@typespec/openapi 0.47.0-dev.1 → 0.47.0-dev.3

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 +102 -57
  2. package/package.json +5 -3
package/README.md CHANGED
@@ -1,105 +1,150 @@
1
- # TypeSpec OpenAPI Library
1
+ # @typespec/openapi
2
2
 
3
- This package provide [TypeSpec](https://github.com/microsoft/typespec) decorators to specify some OpenAPI specific concepts.
3
+ TypeSpec library providing OpenAPI concepts
4
4
 
5
5
  ## Install
6
6
 
7
- In your typespec project root
8
-
9
7
  ```bash
10
8
  npm install @typespec/openapi
11
9
  ```
12
10
 
13
- ## Usage
11
+ ## Decorators
14
12
 
15
- ```typespec
16
- import "@typespec/openapi";
13
+ ### OpenAPI
17
14
 
18
- using OpenAPI;
19
- ```
15
+ - [`@defaultResponse`](#@defaultresponse)
16
+ - [`@extension`](#@extension)
17
+ - [`@externalDocs`](#@externaldocs)
18
+ - [`@info`](#@info)
19
+ - [`@operationId`](#@operationid)
20
20
 
21
- ## References
21
+ #### `@defaultResponse`
22
22
 
23
- Decorators:
23
+ Specify that this model is to be treated as the OpenAPI `default` response.
24
+ This differs from the compiler built-in `@error` decorator as this does not necessarily represent an error.
24
25
 
25
- - [`@defaultResponse`](#defaultResponse)
26
- - [`@extension`](#extension)
27
- - [`@externalDocs`](#externalDocs)
28
- - [`@operationId`](#operationId)
26
+ ```typespec
27
+ @OpenAPI.defaultResponse
28
+ ```
29
29
 
30
- ### `@defaultResponse`
30
+ ##### Target
31
31
 
32
- **IMPORTANT This is to be used on `NON-ERROR` responses that cover all the other status codes. If you are looking to represent an error use [`@error`](https://microsoft.github.io/typespec/docs/standard-library/built-in-decorators/#error)**
32
+ `Model`
33
33
 
34
- Decorator that can be used on a response model to specify the `default` status code that OpenAPI allow.
34
+ ##### Parameters
35
+
36
+ None
37
+
38
+ ##### Examples
35
39
 
36
40
  ```typespec
37
41
  @defaultResponse
38
- model MyNonErrorResponse {}
42
+ model PetStoreResponse is object;
39
43
 
40
- op foo(): MyNonErrorResponse;
44
+ op listPets(): Pet[] | PetStoreResponse;
41
45
  ```
42
46
 
43
- ### `@extension`
47
+ #### `@extension`
44
48
 
45
- This decorator lets you specify custom key(starting with `x-`) value pair that will be added to the OpenAPI document.
46
- [OpenAPI reference on extensions](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#specificationExtensions)
49
+ Attach some custom data to the OpenAPI element generated from this type.
47
50
 
48
- Arguments:
51
+ ```typespec
52
+ @OpenAPI.extension(key: valueof string, value: unknown)
53
+ ```
49
54
 
50
- | Name | foo | Description |
51
- | ------- | ------------ | ---------------------------------------------------------------- |
52
- | `key` | **Required** | Extension key. **MUST** start with `x-` |
53
- | `value` | **Required** | Value of the extension. Can be an primitive, a tuple or a model. |
55
+ ##### Target
54
56
 
55
- ```typespec
56
- @extension("x-custom", "MyCustomValue")
57
- model Foo {}
57
+ `(intrinsic) unknown`
58
+
59
+ ##### Parameters
60
+
61
+ | Name | Type | Description |
62
+ | ----- | ----------------------- | ----------------------------------- |
63
+ | key | `valueof scalar string` | Extension key. Must start with `x-` |
64
+ | value | `(intrinsic) unknown` | Extension value. |
65
+
66
+ ##### Examples
58
67
 
59
- // Value can be an model.
68
+ ```typespec
69
+ @extension("x-custom", "My value")
60
70
  @extension(
61
- "x-custom",
71
+ "x-pageable",
62
72
  {
63
- some: "value",
73
+ nextLink: "x-next-link",
64
74
  }
65
75
  )
66
- model Foo {}
76
+ op read(): string;
77
+ ```
78
+
79
+ #### `@externalDocs`
80
+
81
+ Specify the OpenAPI `externalDocs` property for this type.
82
+
83
+ ```typespec
84
+ @OpenAPI.externalDocs(url: valueof string, description?: valueof string)
67
85
  ```
68
86
 
69
- ### `@externalDocs`
87
+ ##### Target
88
+
89
+ `(intrinsic) unknown`
90
+
91
+ ##### Parameters
92
+
93
+ | Name | Type | Description |
94
+ | ----------- | ----------------------- | ----------------------- |
95
+ | url | `valueof scalar string` | Url to the docs |
96
+ | description | `valueof scalar string` | Description of the docs |
70
97
 
71
- Decorator that can be used to provide the `externalDocs` property on OpenAPI elements.
72
- [OpenAPI spec for externalDocs](https://github.com/OAI/OpenAPI-Specification/blob/3.0.3/versions/3.0.3.md#externalDocumentationObject)
98
+ ##### Examples
99
+
100
+ ```typespec
101
+ @externalDocs(
102
+ "https://example.com/detailed.md",
103
+ "Detailed information on how to use this operation"
104
+ )
105
+ op listPets(): Pet[];
106
+ ```
73
107
 
74
- Arguments:
108
+ #### `@info`
75
109
 
76
- | Name | foo | Description |
77
- | ------------- | ------------ | -------------------------------- |
78
- | `url` | **Required** | Url for the external docs |
79
- | `description` | **Optional** | Description of the documentation |
110
+ Specify OpenAPI additional information.
111
+ The service `title` and `version` are already specified using `@service`.
80
112
 
81
113
  ```typespec
82
- @externalDocs("https://example.com", "More info there")
83
- model Foo {}
114
+ @OpenAPI.info(additionalInfo: OpenAPI.AdditionalInfo)
84
115
  ```
85
116
 
86
- ### `@operationId`
117
+ ##### Target
87
118
 
88
- Decorator that can be used on an operation to specify the `operationId` field in OpenAPI. If this is not provided the `operationId` will be the typespec operation name.
119
+ `Namespace`
89
120
 
90
- Arguments:
121
+ ##### Parameters
91
122
 
92
- | Name | foo | Description |
93
- | ------ | ------------ | ------------------- |
94
- | `opId` | **Required** | Id of the operation |
123
+ | Name | Type | Description |
124
+ | -------------- | ------------------------------ | ---------------------- |
125
+ | additionalInfo | `model OpenAPI.AdditionalInfo` | Additional information |
126
+
127
+ #### `@operationId`
128
+
129
+ Specify the OpenAPI `operationId` property for this operation.
95
130
 
96
131
  ```typespec
97
- @operationId("custom_Foo")
98
- op foo(): string;
132
+ @OpenAPI.operationId(operationId: valueof string)
99
133
  ```
100
134
 
101
- ## See also
135
+ ##### Target
136
+
137
+ `Operation`
138
+
139
+ ##### Parameters
102
140
 
103
- - [TypeSpec Getting Started](https://github.com/microsoft/typespec#getting-started)
104
- - [TypeSpec Website](https://microsoft.github.io/typespec)
105
- - [TypeSpec for the OpenAPI Developer](https://github.com/microsoft/typespec/blob/main/docs/typespec-for-openapi-dev.md)
141
+ | Name | Type | Description |
142
+ | ----------- | ----------------------- | ------------------- |
143
+ | operationId | `valueof scalar string` | Operation id value. |
144
+
145
+ ##### Examples
146
+
147
+ ```typespec
148
+ @operationId("download")
149
+ op read(): string;
150
+ ```
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "@typespec/openapi",
3
- "version": "0.47.0-dev.1",
3
+ "version": "0.47.0-dev.3",
4
4
  "author": "Microsoft Corporation",
5
5
  "description": "TypeSpec library providing OpenAPI concepts",
6
6
  "homepage": "https://microsoft.github.io/typespec",
7
- "readme": "https://github.com/microsoft/typespec/blob/master/README.md",
7
+ "readme": "https://github.com/microsoft/typespec/blob/main/README.md",
8
8
  "license": "MIT",
9
9
  "repository": {
10
10
  "type": "git",
@@ -55,6 +55,7 @@
55
55
  "@typespec/eslint-config-typespec": "~0.46.0 || >=0.47.0-dev <0.47.0",
56
56
  "@typespec/library-linter": "~0.46.0 || >=0.47.0-dev <0.47.0",
57
57
  "@typespec/eslint-plugin": "~0.46.0 || >=0.47.0-dev <0.47.0",
58
+ "@typespec/tspd": "~0.46.0 || >=0.47.0-dev <0.47.0",
58
59
  "eslint": "^8.42.0",
59
60
  "mocha": "~10.2.0",
60
61
  "mocha-junit-reporter": "~2.2.0",
@@ -72,6 +73,7 @@
72
73
  "test": "mocha",
73
74
  "test-official": "c8 mocha --forbid-only --reporter mocha-multi-reporters",
74
75
  "lint": "eslint . --ext .ts --max-warnings=0",
75
- "lint:fix": "eslint . --fix --ext .ts"
76
+ "lint:fix": "eslint . --fix --ext .ts",
77
+ "regen-docs": "tspd doc . --enable-experimental --output-dir ../../docs/standard-library/openapi/reference"
76
78
  }
77
79
  }