Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improved ref docs for model #2951

Merged
merged 25 commits into from
Feb 29, 2024
Merged

Improved ref docs for model #2951

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
5ceabf7
Show properties
timotheeguerin Feb 23, 2024
5e5bee4
Link to data types
timotheeguerin Feb 23, 2024
6715c6a
Show docs
timotheeguerin Feb 23, 2024
a2301a7
Regen docs
timotheeguerin Feb 23, 2024
d9cfe6d
Create ref-docs-models-2024-1-23-22-27-5.md
timotheeguerin Feb 23, 2024
e657708
Indexer
timotheeguerin Feb 23, 2024
48ff6d5
Fix
timotheeguerin Feb 23, 2024
1f3503c
Handle nested types
timotheeguerin Feb 23, 2024
a87cfe2
.
timotheeguerin Feb 23, 2024
c59670c
Better string type name
timotheeguerin Feb 23, 2024
5a598e7
Create ref-docs-models-2024-1-24-0-0-44.md
timotheeguerin Feb 24, 2024
ac30058
Update ref-docs-models-2024-1-23-22-27-5.md
timotheeguerin Feb 24, 2024
2391045
fix some docs
timotheeguerin Feb 24, 2024
203c9a9
Add simple model rendering test
timotheeguerin Feb 24, 2024
e221aea
fix tests
timotheeguerin Feb 26, 2024
4f08b5b
more fixes
timotheeguerin Feb 26, 2024
046f3dc
more fixes
timotheeguerin Feb 26, 2024
5c7b2a8
fix extra br
timotheeguerin Feb 26, 2024
5b77c53
none for no props
timotheeguerin Feb 26, 2024
8d65194
Better ref naming
timotheeguerin Feb 26, 2024
5186103
Fix
timotheeguerin Feb 26, 2024
fa43a17
Update .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md
timotheeguerin Feb 26, 2024
7cfe9ea
Merge branch 'main' of https://github.com/Microsoft/typespec into ref…
timotheeguerin Feb 29, 2024
610d6e0
merge
timotheeguerin Feb 29, 2024
fa312fb
fix tests
timotheeguerin Feb 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
---
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
changeKind: internal
packages:
- "@typespec/http"
timotheeguerin marked this conversation as resolved.
Show resolved Hide resolved
- "@typespec/openapi3"
- "@typespec/rest"
- "@typespec/json-schema"
- "@typespec/openapi"
- "@typespec/protobuf"
- "@typespec/versioning"
---

8 changes: 8 additions & 0 deletions .chronus/changes/ref-docs-models-2024-1-24-0-0-44.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
---
# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
changeKind: fix
packages:
- "@typespec/compiler"
---

Wrap string in quotes in errors
183 changes: 183 additions & 0 deletions docs/libraries/http/reference/data-types.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,12 @@ The request has been accepted for processing, but processing has not yet complet
model TypeSpec.Http.AcceptedResponse
```

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `202` | The status code. |

### `ApiKeyAuth` {#TypeSpec.Http.ApiKeyAuth}

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

#### Properties

| Name | Type | Description |
| ---- | ------------------------------- | ----------- |
| type | `TypeSpec.Http.AuthType.apiKey` | |
| in | `Location` | |
| name | `Name` | |

### `AuthorizationCodeFlow` {#TypeSpec.Http.AuthorizationCodeFlow}

Authorization Code flow
Expand All @@ -57,6 +71,16 @@ Authorization Code flow
model TypeSpec.Http.AuthorizationCodeFlow
```

#### Properties

| Name | Type | Description |
| ---------------- | ------------------------------------------------ | --------------------------------- |
| type | `TypeSpec.Http.OAuth2FlowType.authorizationCode` | authorization code flow |
| authorizationUrl | `string` | the authorization URL |
| tokenUrl | `string` | the token URL |
| refreshUrl? | `string` | the refresh URL |
| scopes? | `string[]` | list of scopes for the credential |

### `BadRequestResponse` {#TypeSpec.Http.BadRequestResponse}

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

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `400` | The status code. |

### `BasicAuth` {#TypeSpec.Http.BasicAuth}

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

#### Properties

| Name | Type | Description |
| ------ | ----------------------------- | ------------------- |
| type | `TypeSpec.Http.AuthType.http` | Http authentication |
| scheme | `"basic"` | basic auth scheme |

### `BearerAuth` {#TypeSpec.Http.BearerAuth}

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

#### Properties

| Name | Type | Description |
| ------ | ----------------------------- | ------------------- |
| type | `TypeSpec.Http.AuthType.http` | Http authentication |
| scheme | `"bearer"` | bearer auth scheme |

### `Body` {#TypeSpec.Http.Body}

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

#### Properties

| Name | Type | Description |
| ---- | ------ | ----------- |
| body | `Type` | |

### `ClientCredentialsFlow` {#TypeSpec.Http.ClientCredentialsFlow}

Client credentials flow
Expand All @@ -118,6 +168,15 @@ Client credentials flow
model TypeSpec.Http.ClientCredentialsFlow
```

#### Properties

| Name | Type | Description |
| ----------- | ------------------------------------------------ | --------------------------------- |
| type | `TypeSpec.Http.OAuth2FlowType.clientCredentials` | client credential flow |
| tokenUrl | `string` | the token URL |
| refreshUrl? | `string` | the refresh URL |
| scopes? | `string[]` | list of scopes for the credential |

### `ConflictResponse` {#TypeSpec.Http.ConflictResponse}

The request conflicts with the current state of the server.
Expand All @@ -126,6 +185,12 @@ The request conflicts with the current state of the server.
model TypeSpec.Http.ConflictResponse
```

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `409` | The status code. |

### `CreatedResponse` {#TypeSpec.Http.CreatedResponse}

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

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `201` | The status code. |

### `ForbiddenResponse` {#TypeSpec.Http.ForbiddenResponse}

Access is forbidden.
Expand All @@ -142,6 +213,12 @@ Access is forbidden.
model TypeSpec.Http.ForbiddenResponse
```

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `403` | The status code. |

### `HeaderOptions` {#TypeSpec.Http.HeaderOptions}

Header options.
Expand All @@ -150,6 +227,13 @@ Header options.
model TypeSpec.Http.HeaderOptions
```

#### Properties

| Name | Type | Description |
| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| name? | `string` | Name of the header when sent over HTTP. |
| format? | `"csv" \| "multi" \| "tsv" \| "ssv" \| "pipes" \| "simple" \| "form"` | Determines the format of the array if type array is used. |

### `ImplicitFlow` {#TypeSpec.Http.ImplicitFlow}

Implicit flow
Expand All @@ -158,6 +242,15 @@ Implicit flow
model TypeSpec.Http.ImplicitFlow
```

#### Properties

| Name | Type | Description |
| ---------------- | --------------------------------------- | --------------------------------- |
| type | `TypeSpec.Http.OAuth2FlowType.implicit` | implicit flow |
| authorizationUrl | `string` | the authorization URL |
| refreshUrl? | `string` | the refresh URL |
| scopes? | `string[]` | list of scopes for the credential |

### `LocationHeader` {#TypeSpec.Http.LocationHeader}

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

#### Properties

| Name | Type | Description |
| -------- | -------- | --------------------------------------------------------------------------------------------------- |
| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. |

### `MovedResponse` {#TypeSpec.Http.MovedResponse}

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

#### Properties

| Name | Type | Description |
| ---------- | -------- | --------------------------------------------------------------------------------------------------- |
| statusCode | `301` | The status code. |
| location | `string` | The Location header contains the URL where the status of the long running operation can be checked. |

### `NoAuth` {#TypeSpec.Http.NoAuth}

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

#### Properties

| Name | Type | Description |
| ---- | ------------------------------- | ----------- |
| type | `TypeSpec.Http.AuthType.noAuth` | |

### `NoContentResponse` {#TypeSpec.Http.NoContentResponse}

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

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `204` | The status code. |

### `NotFoundResponse` {#TypeSpec.Http.NotFoundResponse}

The server cannot find the requested resource.
Expand All @@ -199,6 +317,12 @@ The server cannot find the requested resource.
model TypeSpec.Http.NotFoundResponse
```

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `404` | The status code. |

### `NotModifiedResponse` {#TypeSpec.Http.NotModifiedResponse}

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

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `304` | The status code. |

### `OAuth2Auth` {#TypeSpec.Http.OAuth2Auth}

OAuth 2.0 is an authorization protocol that gives an API client limited access to user data on a web server.
Expand All @@ -226,6 +356,14 @@ model TypeSpec.Http.OAuth2Auth<Flows, Scopes>
| Flows | The list of supported OAuth2 flows |
| 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. |

#### Properties

| Name | Type | Description |
| ------------- | ------------------------------- | ----------- |
| type | `TypeSpec.Http.AuthType.oauth2` | |
| flows | `Flows` | |
| defaultScopes | `Scopes` | |

### `OkResponse` {#TypeSpec.Http.OkResponse}

The request has succeeded.
Expand All @@ -234,6 +372,12 @@ The request has succeeded.
model TypeSpec.Http.OkResponse
```

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `200` | The status code. |

### `OpenIdConnectAuth` {#TypeSpec.Http.OpenIdConnectAuth}

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.
Expand All @@ -255,6 +399,13 @@ model TypeSpec.Http.OpenIdConnectAuth<ConnectUrl>
| ---------- | ----------- |
| ConnectUrl | |

#### Properties

| Name | Type | Description |
| ---------------- | -------------------------------------- | ----------------------------------------------------------- |
| type | `TypeSpec.Http.AuthType.openIdConnect` | Auth type |
| openIdConnectUrl | `ConnectUrl` | Connect url. It can be specified relative to the server URL |

### `PasswordFlow` {#TypeSpec.Http.PasswordFlow}

Resource Owner Password flow
Expand All @@ -263,6 +414,15 @@ Resource Owner Password flow
model TypeSpec.Http.PasswordFlow
```

#### Properties

| Name | Type | Description |
| ---------------- | --------------------------------------- | --------------------------------- |
| type | `TypeSpec.Http.OAuth2FlowType.password` | password flow |
| authorizationUrl | `string` | the authorization URL |
| refreshUrl? | `string` | the refresh URL |
| scopes? | `string[]` | list of scopes for the credential |

### `PlainData` {#TypeSpec.Http.PlainData}

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

#### Properties

None

### `QueryOptions` {#TypeSpec.Http.QueryOptions}

Query parameter options.
Expand All @@ -286,6 +450,13 @@ Query parameter options.
model TypeSpec.Http.QueryOptions
```

#### Properties

| Name | Type | Description |
| ------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| name? | `string` | Name of the query when included in the url. |
| format? | `"multi" \| "csv" \| "ssv" \| "tsv" \| "simple" \| "form" \| "pipes"` | Determines the format of the array if type array is used. |

### `Response` {#TypeSpec.Http.Response}

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

#### Properties

| Name | Type | Description |
| ---------- | -------- | ----------- |
| statusCode | `Status` | |

### `UnauthorizedResponse` {#TypeSpec.Http.UnauthorizedResponse}

Access is unauthorized.
Expand All @@ -308,6 +485,12 @@ Access is unauthorized.
model TypeSpec.Http.UnauthorizedResponse
```

#### Properties

| Name | Type | Description |
| ---------- | ----- | ---------------- |
| statusCode | `401` | The status code. |

### `ApiKeyLocation` {#TypeSpec.Http.ApiKeyLocation}

Describes the location of the API key
Expand Down
Loading
Loading