Skip to content

Commit 02ed01e

Browse files
timotheeguerintimotheeguerin
authored
Improved ref docs for model (microsoft#2951)
fix Azure/typespec-azure-pr#3861 fix microsoft#2232 Generate docs for model properties and reference models within the same package <img width="1213" alt="image" src="https://github.com/microsoft/typespec/assets/1031227/ae7eccd0-97d8-401e-b07f-3375c7b41446">
1 parent 717af64 commit 02ed01e

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+1277
-584
lines changed

‎.chronus/changes/ref-docs-models-2024-1-23-22-27-5.md

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
3+
changeKind: internal
4+
packages:
5+
- "@typespec/http"
6+
- "@typespec/openapi3"
7+
- "@typespec/rest"
8+
- "@typespec/json-schema"
9+
- "@typespec/openapi"
10+
- "@typespec/protobuf"
11+
- "@typespec/versioning"
12+
---
13+

‎.chronus/changes/ref-docs-models-2024-1-24-0-0-44.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
3+
changeKind: fix
4+
packages:
5+
- "@typespec/compiler"
6+
---
7+
8+
Wrap string in quotes in errors

‎docs/libraries/http/reference/data-types.md

+183
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,12 @@ The request has been accepted for processing, but processing has not yet complet
1616
model TypeSpec.Http.AcceptedResponse
1717
```
1818

19+
#### Properties
20+
21+
| Name | Type | Description |
22+
| ---------- | ----- | ---------------- |
23+
| statusCode | `202` | The status code. |
24+
1925
### `ApiKeyAuth` {#TypeSpec.Http.ApiKeyAuth}
2026

2127
An API key is a token that a client provides when making API calls. The key can be sent in the query string:
@@ -49,6 +55,14 @@ model TypeSpec.Http.ApiKeyAuth<Location, Name>
4955
| Location | The location of the API key |
5056
| Name | The name of the API key |
5157

58+
#### Properties
59+
60+
| Name | Type | Description |
61+
| ---- | ------------------------------- | ----------- |
62+
| type | `TypeSpec.Http.AuthType.apiKey` | |
63+
| in | `Location` | |
64+
| name | `Name` | |
65+
5266
### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow}
5367

5468
Authorization Code flow
@@ -57,6 +71,16 @@ Authorization Code flow
5771
model TypeSpec.Http.AuthorizationCodeFlow
5872
```
5973

74+
#### Properties
75+
76+
| Name | Type | Description |
77+
| ---------------- | ------------------------------------------------ | --------------------------------- |
78+
| type | `TypeSpec.Http.OAuth2FlowType.authorizationCode` | authorization code flow |
79+
| authorizationUrl | `string` | the authorization URL |
80+
| tokenUrl | `string` | the token URL |
81+
| refreshUrl? | `string` | the refresh URL |
82+
| scopes? | `string[]` | list of scopes for the credential |
83+
6084
### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse}
6185

6286
The server could not understand the request due to invalid syntax.
@@ -65,6 +89,12 @@ The server could not understand the request due to invalid syntax.
6589
model TypeSpec.Http.BadRequestResponse
6690
```
6791

92+
#### Properties
93+
94+
| Name | Type | Description |
95+
| ---------- | ----- | ---------------- |
96+
| statusCode | `400` | The status code. |
97+
6898
### `BasicAuth` {#TypeSpec.Http.BasicAuth}
6999

70100
Basic authentication is a simple authentication scheme built into the HTTP protocol.
@@ -79,6 +109,13 @@ Authorization: Basic ZGVtbzpwQDU1dzByZA==
79109
model TypeSpec.Http.BasicAuth
80110
```
81111

112+
#### Properties
113+
114+
| Name | Type | Description |
115+
| ------ | ----------------------------- | ------------------- |
116+
| type | `TypeSpec.Http.AuthType.http` | Http authentication |
117+
| scheme | `"basic"` | basic auth scheme |
118+
82119
### `BearerAuth` {#TypeSpec.Http.BearerAuth}
83120

84121
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens.
@@ -93,6 +130,13 @@ Authorization: Bearer <token>
93130
model TypeSpec.Http.BearerAuth
94131
```
95132

133+
#### Properties
134+
135+
| Name | Type | Description |
136+
| ------ | ----------------------------- | ------------------- |
137+
| type | `TypeSpec.Http.AuthType.http` | Http authentication |
138+
| scheme | `"bearer"` | bearer auth scheme |
139+
96140
### `Body` {#TypeSpec.Http.Body}
97141

98142
Defines a model with a single property of the given type, marked with `@body`.
@@ -110,6 +154,12 @@ model TypeSpec.Http.Body<Type>
110154
| ---- | ---------------------------------------- |
111155
| Type | The type of the model's `body` property. |
112156

157+
#### Properties
158+
159+
| Name | Type | Description |
160+
| ---- | ------ | ----------- |
161+
| body | `Type` | |
162+
113163
### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow}
114164

115165
Client credentials flow
@@ -118,6 +168,15 @@ Client credentials flow
118168
model TypeSpec.Http.ClientCredentialsFlow
119169
```
120170

171+
#### Properties
172+
173+
| Name | Type | Description |
174+
| ----------- | ------------------------------------------------ | --------------------------------- |
175+
| type | `TypeSpec.Http.OAuth2FlowType.clientCredentials` | client credential flow |
176+
| tokenUrl | `string` | the token URL |
177+
| refreshUrl? | `string` | the refresh URL |
178+
| scopes? | `string[]` | list of scopes for the credential |
179+
121180
### `ConflictResponse` {#TypeSpec.Http.ConflictResponse}
122181

123182
The request conflicts with the current state of the server.
@@ -126,6 +185,12 @@ The request conflicts with the current state of the server.
126185
model TypeSpec.Http.ConflictResponse
127186
```
128187

188+
#### Properties
189+
190+
| Name | Type | Description |
191+
| ---------- | ----- | ---------------- |
192+
| statusCode | `409` | The status code. |
193+
129194
### `CreatedResponse` {#TypeSpec.Http.CreatedResponse}
130195

131196
The request has succeeded and a new resource has been created as a result.
@@ -134,6 +199,12 @@ The request has succeeded and a new resource has been created as a result.
134199
model TypeSpec.Http.CreatedResponse
135200
```
136201

202+
#### Properties
203+
204+
| Name | Type | Description |
205+
| ---------- | ----- | ---------------- |
206+
| statusCode | `201` | The status code. |
207+
137208
### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse}
138209

139210
Access is forbidden.
@@ -142,6 +213,12 @@ Access is forbidden.
142213
model TypeSpec.Http.ForbiddenResponse
143214
```
144215

216+
#### Properties
217+
218+
| Name | Type | Description |
219+
| ---------- | ----- | ---------------- |
220+
| statusCode | `403` | The status code. |
221+
145222
### `HeaderOptions` {#TypeSpec.Http.HeaderOptions}
146223

147224
Header options.
@@ -150,6 +227,13 @@ Header options.
150227
model TypeSpec.Http.HeaderOptions
151228
```
152229

230+
#### Properties
231+
232+
| Name | Type | Description |
233+
| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
234+
| name? | `string` | Name of the header when sent over HTTP. |
235+
| format? | `"csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. |
236+
153237
### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow}
154238

155239
Implicit flow
@@ -158,6 +242,15 @@ Implicit flow
158242
model TypeSpec.Http.ImplicitFlow
159243
```
160244

245+
#### Properties
246+
247+
| Name | Type | Description |
248+
| ---------------- | --------------------------------------- | --------------------------------- |
249+
| type | `TypeSpec.Http.OAuth2FlowType.implicit` | implicit flow |
250+
| authorizationUrl | `string` | the authorization URL |
251+
| refreshUrl? | `string` | the refresh URL |
252+
| scopes? | `string[]` | list of scopes for the credential |
253+
161254
### `LocationHeader` {#TypeSpec.Http.LocationHeader}
162255

163256
The Location header contains the URL where the status of the long running operation can be checked.
@@ -166,6 +259,12 @@ The Location header contains the URL where the status of the long running operat
166259
model TypeSpec.Http.LocationHeader
167260
```
168261

262+
#### Properties
263+
264+
| Name | Type | Description |
265+
| -------- | -------- | --------------------------------------------------------------------------------------------------- |
266+
| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. |
267+
169268
### `MovedResponse` {#TypeSpec.Http.MovedResponse}
170269

171270
The URL of the requested resource has been changed permanently. The new URL is given in the response.
@@ -174,6 +273,13 @@ The URL of the requested resource has been changed permanently. The new URL is g
174273
model TypeSpec.Http.MovedResponse
175274
```
176275

276+
#### Properties
277+
278+
| Name | Type | Description |
279+
| ---------- | -------- | --------------------------------------------------------------------------------------------------- |
280+
| statusCode | `301` | The status code. |
281+
| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. |
282+
177283
### `NoAuth` {#TypeSpec.Http.NoAuth}
178284

179285
This authentication option signifies that API is not secured at all.
@@ -183,6 +289,12 @@ It might be useful when overriding authentication on interface of operation leve
183289
model TypeSpec.Http.NoAuth
184290
```
185291

292+
#### Properties
293+
294+
| Name | Type | Description |
295+
| ---- | ------------------------------- | ----------- |
296+
| type | `TypeSpec.Http.AuthType.noAuth` | |
297+
186298
### `NoContentResponse` {#TypeSpec.Http.NoContentResponse}
187299

188300
There is no content to send for this request, but the headers may be useful.
@@ -191,6 +303,12 @@ There is no content to send for this request, but the headers may be useful.
191303
model TypeSpec.Http.NoContentResponse
192304
```
193305

306+
#### Properties
307+
308+
| Name | Type | Description |
309+
| ---------- | ----- | ---------------- |
310+
| statusCode | `204` | The status code. |
311+
194312
### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse}
195313

196314
The server cannot find the requested resource.
@@ -199,6 +317,12 @@ The server cannot find the requested resource.
199317
model TypeSpec.Http.NotFoundResponse
200318
```
201319

320+
#### Properties
321+
322+
| Name | Type | Description |
323+
| ---------- | ----- | ---------------- |
324+
| statusCode | `404` | The status code. |
325+
202326
### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse}
203327

204328
The client has made a conditional request and the resource has not been modified.
@@ -207,6 +331,12 @@ The client has made a conditional request and the resource has not been modified
207331
model TypeSpec.Http.NotModifiedResponse
208332
```
209333

334+
#### Properties
335+
336+
| Name | Type | Description |
337+
| ---------- | ----- | ---------------- |
338+
| statusCode | `304` | The status code. |
339+
210340
### `OAuth2Auth` {#TypeSpec.Http.OAuth2Auth}
211341

212342
OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
@@ -226,6 +356,14 @@ model TypeSpec.Http.OAuth2Auth<Flows, Scopes>
226356
| Flows | The list of supported OAuth2 flows |
227357
| Scopes | The list of OAuth2 scopes, which are common for every flow from `Flows`. This list is combined with the scopes defined in specific OAuth2 flows. |
228358

359+
#### Properties
360+
361+
| Name | Type | Description |
362+
| ------------- | ------------------------------- | ----------- |
363+
| type | `TypeSpec.Http.AuthType.oauth2` | |
364+
| flows | `Flows` | |
365+
| defaultScopes | `Scopes` | |
366+
229367
### `OkResponse` {#TypeSpec.Http.OkResponse}
230368

231369
The request has succeeded.
@@ -234,6 +372,12 @@ The request has succeeded.
234372
model TypeSpec.Http.OkResponse
235373
```
236374

375+
#### Properties
376+
377+
| Name | Type | Description |
378+
| ---------- | ----- | ---------------- |
379+
| statusCode | `200` | The status code. |
380+
237381
### `OpenIdConnectAuth` {#TypeSpec.Http.OpenIdConnectAuth}
238382

239383
OpenID Connect (OIDC) is an identity layer built on top of the OAuth 2.0 protocol and supported by some OAuth 2.0 providers, such as Google and Azure Active Directory.
@@ -255,6 +399,13 @@ model TypeSpec.Http.OpenIdConnectAuth<ConnectUrl>
255399
| ---------- | ----------- |
256400
| ConnectUrl | |
257401

402+
#### Properties
403+
404+
| Name | Type | Description |
405+
| ---------------- | -------------------------------------- | ----------------------------------------------------------- |
406+
| type | `TypeSpec.Http.AuthType.openIdConnect` | Auth type |
407+
| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL |
408+
258409
### `PasswordFlow` {#TypeSpec.Http.PasswordFlow}
259410

260411
Resource Owner Password flow
@@ -263,6 +414,15 @@ Resource Owner Password flow
263414
model TypeSpec.Http.PasswordFlow
264415
```
265416

417+
#### Properties
418+
419+
| Name | Type | Description |
420+
| ---------------- | --------------------------------------- | --------------------------------- |
421+
| type | `TypeSpec.Http.OAuth2FlowType.password` | password flow |
422+
| authorizationUrl | `string` | the authorization URL |
423+
| refreshUrl? | `string` | the refresh URL |
424+
| scopes? | `string[]` | list of scopes for the credential |
425+
266426
### `PlainData` {#TypeSpec.Http.PlainData}
267427

268428
Produces a new model with the same properties as T, but with `@query`,
@@ -278,6 +438,10 @@ model TypeSpec.Http.PlainData<Data>
278438
| ---- | -------------------------------------- |
279439
| Data | The model to spread as the plain data. |
280440

441+
#### Properties
442+
443+
None
444+
281445
### `QueryOptions` {#TypeSpec.Http.QueryOptions}
282446

283447
Query parameter options.
@@ -286,6 +450,13 @@ Query parameter options.
286450
model TypeSpec.Http.QueryOptions
287451
```
288452

453+
#### Properties
454+
455+
| Name | Type | Description |
456+
| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
457+
| name? | `string` | Name of the query when included in the url. |
458+
| format? | `"multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. |
459+
289460
### `Response` {#TypeSpec.Http.Response}
290461

291462
Describes an HTTP response.
@@ -300,6 +471,12 @@ model TypeSpec.Http.Response<Status>
300471
| ------ | -------------------------------- |
301472
| Status | The status code of the response. |
302473

474+
#### Properties
475+
476+
| Name | Type | Description |
477+
| ---------- | -------- | ----------- |
478+
| statusCode | `Status` | |
479+
303480
### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse}
304481

305482
Access is unauthorized.
@@ -308,6 +485,12 @@ Access is unauthorized.
308485
model TypeSpec.Http.UnauthorizedResponse
309486
```
310487

488+
#### Properties
489+
490+
| Name | Type | Description |
491+
| ---------- | ----- | ---------------- |
492+
| statusCode | `401` | The status code. |
493+
311494
### `ApiKeyLocation` {#TypeSpec.Http.ApiKeyLocation}
312495

313496
Describes the location of the API key

0 commit comments

Comments
 (0)