Skip to content

Commit

Permalink
Improved ref docs for model (#2951)
Browse files Browse the repository at this point in the history 
fix Azure/typespec-azure-pr#3861
fix #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">
  • Loading branch information
@timotheeguerin
timotheeguerin committed Feb 29, 2024
1 parent 717af64 commit 02ed01e
Show file tree
Hide file tree
Showing 45 changed files with 1,277 additions and 584 deletions.
13 changes: 13 additions & 0 deletions .chronus/changes/ref-docs-models-2024-1-23-22-27-5.md
View file
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"
- "@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
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
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

0 comments on commit 02ed01e

Please sign in to comment.