Updating tutorial doc and http/rest library doc (#729)
* initial doc update * ... * . * additional doc update * update links * minor update * update changelog Co-authored-by: JianyeXi <59603451+jianyexi@users.noreply.github.com>
This commit is contained in:
Allen Zhang
GitHub
Родитель
d576dd8638
Коммит
e63e8b59e8
|
|
@ -0,0 +1,10 @@
|
|||
{
|
||||
"changes": [
|
||||
{
|
||||
"packageName": "@cadl-lang/rest",
|
||||
"comment": "readme.md documentation change",
|
||||
"type": "none"
|
||||
}
|
||||
],
|
||||
"packageName": "@cadl-lang/rest"
|
||||
}
|
||||
|
|
@ -15,15 +15,15 @@ Cadl's primary benefits include:
|
|||
|
||||
Cadl consists of the following language features:
|
||||
|
||||
- Models: data shapes or schemas
|
||||
- Type Literals: strings and numbers with specific values
|
||||
- Type Operators: syntax for composing model types into other types
|
||||
- Operations: service endpoints with parameters and return values
|
||||
- Namespaces & Usings: groups models and operations together into hierarchical groups with friendly names
|
||||
- Interfaces: groups operations
|
||||
- Imports: links declarations across multiple files and libraries together into a single program
|
||||
- Decorators: bits of TypeScript code that add metadata or sometimes mutate declarations
|
||||
- Libraries: encapsulate Cadl definitions into reusable components
|
||||
- [Models](#Models): data shapes or schemas
|
||||
- [Type Literals](#Type-Literals): strings and numbers with specific values
|
||||
- [Type Operators](#Type-Operators): syntax for composing model types into other types
|
||||
- [Operations](#Operations): service endpoints with parameters and return values
|
||||
- [Namespaces & Usings](#Namespaces-&-Usings): groups models and operations together into hierarchical groups with friendly names
|
||||
- [Interfaces](#Interfaces): groups operations
|
||||
- [Imports](#Imports): links declarations across multiple files and libraries together into a single program
|
||||
- [Decorators](#Decorators): bits of TypeScript code that add metadata or sometimes mutate declarations
|
||||
- [Libraries](#Libraries): encapsulate Cadl definitions into reusable components
|
||||
|
||||
In addition, Cadl comes with a standard library for describing REST APIs and generating OpenAPI. Other protocol bindings are a work in progress!
|
||||
|
||||
|
|
@ -97,7 +97,7 @@ model Dog {
|
|||
|
||||
#### Extends
|
||||
|
||||
Sometimes you want to create an explicit relationship between two models, for example when you want to emit class definitions in languages which support inheritance. The `extends` keyword can be used to establish such a relationship.
|
||||
Sometimes you want to create an explicit relationship between two models, for example when you want to emit class definitions in languages which support inheritance. The `extends` keyword can be used to establish such a relationship. It is also used extensively with `interface` to compose from existing interface building blocks.
|
||||
|
||||
```cadl
|
||||
model Animal {
|
||||
|
|
@ -690,6 +690,15 @@ emitters:
|
|||
--option "@cadl-lang/openapi3.output-file=my-custom-file.json"
|
||||
```
|
||||
|
||||
#### Standard emitter libraries
|
||||
|
||||
Cadl has following standard libraries:
|
||||
| Library | Package name | Documentation | Source |
|
||||
|---|---|---|---|
|
||||
| OpenAPI binding library | @cadl-lang/openapi| [Readme.md](https://github.com/microsoft/cadl/tree/main/packages/openapi/README.md)| [Link](https://github.com/microsoft/cadl/tree/main/packages/openapi)
|
||||
| OpenAPI 3 | @cadl-lang/openapi3| [Readme.md](https://github.com/microsoft/cadl/tree/main/packages/openapi3/README.md)|[Link](https://github.com/microsoft/cadl/tree/main/packages/openapi)
|
||||
| HTTP, REST | @cadl-lang/rest | [Readme.md](https://github.com/microsoft/cadl/tree/main/packages/rest/README.md)|[Link](https://github.com/microsoft/cadl/tree/main/packages/openapi)
|
||||
|
||||
#### Creating libraries
|
||||
|
||||
Creating a Cadl library is essentially the same as creating any NPM library. [Consult the official documentation for more info](https://docs.npmjs.com/creating-node-js-modules). `main` should refer to a JS file that exports all your library's decorators and helper utilities.
|
||||
|
|
@ -702,7 +711,7 @@ With the language building blocks we've covered so far we're ready to author our
|
|||
|
||||
Cadl also has an official OpenAPI emitter called `@cadl-lang/openapi3` that consumes the REST API bindings and emits standard OpenAPI descriptions. This can then be fed in to any OpenAPI code generation pipeline.
|
||||
|
||||
The following examples assume you have imported both `@cadl-lang/openapi3` and `@cadl-lang/rest` somewhere in your Cadl program (though importing them in `main.cadl` is the standard convention).
|
||||
The following examples assume you have imported both `@cadl-lang/openapi3` and `@cadl-lang/rest` somewhere in your Cadl program (though importing them in `main.cadl` is the standard convention). For detailed library reference, please see rest library's [Readme.md](https://github.com/microsoft/cadl/blob/main/packages/rest/README.md).
|
||||
|
||||
#### Service definition and metadata
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Cadl Rest Library
|
||||
# Cadl HTTP/Rest Library
|
||||
|
||||
This package provides [Cadl](htps://github.com/microsoft/Cadl) decorators to describe REST API.
|
||||
This package provides [Cadl](htps://github.com/microsoft/Cadl) decorators, models, and interfaces to describe HTTP and REST API. With fundamental models and decorators defined in Cadl.Http namespace, you will be able describe basic http level operations. Cadl.Rest namespace adds additional predefined models and interfaces. These building blocks make defining REST resources and operations based on standard patterns extremely simple.
|
||||
|
||||
## Install
|
||||
|
||||
|
|
@ -12,84 +12,161 @@ npm install @cadl-lang/rest
|
|||
|
||||
## Usage
|
||||
|
||||
See [Rest section in the tutorial](../../docs/tutorial.md#rest-apis)
|
||||
```Cadl
|
||||
import "@cadl-lang/rest";
|
||||
|
||||
using Cadl.Http;
|
||||
using Cadl.Rest;
|
||||
```
|
||||
|
||||
See [Rest section in the tutorial](https://github.com/microsoft/cadl/blob/main/docs/tutorial.md#rest-apis)
|
||||
|
||||
## Library Tour
|
||||
|
||||
`@cadl-lang/rest` library defines of the following artifacts:
|
||||
|
||||
- [Models](#models)
|
||||
- [Decorators](#decorators)
|
||||
- [Interfaces](#interfaces)
|
||||
|
||||
## Models
|
||||
|
||||
- ### HTTP namespace
|
||||
| Model | Notes |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| LocationHeader | Location header |
|
||||
| Response<Status> | <Status> is numerical status code. |
|
||||
| OkResponse<T> | Response<200> with T as the response body model type. |
|
||||
| CreatedResponse | Response<201> |
|
||||
| AcceptedResponse | Response<202> |
|
||||
| NoContentResponse | Response<204> |
|
||||
| MovedResponse | Response<301> with LocationHeader for redirected URL |
|
||||
| NotModifiedResponse | Response<304> |
|
||||
| UnauthorizedResponse | Response<401> |
|
||||
| NotFoundResponse | Response<404> |
|
||||
| ConflictResponse | Response<409> |
|
||||
| PlainData<T> | Produces a new model with the same properties as T, but with @query, @header, @body, and @path decorators removed from all properties. |
|
||||
- ### REST namespace
|
||||
| Model | Notes |
|
||||
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
|
||||
| KeysOf<T> | Dynamically gathers keys of the model type T. |
|
||||
| Page<T> | A model defines page of T which includes an array of T and optional next link. |
|
||||
| ParentKeysOf<T> | Dynamically gathers parent keys of the model type T, which are referenced with `@parentResource` decorator. |
|
||||
| ResourceError | The default error response for resource operations that includes <br> `code: int32` and `message string`. |
|
||||
| ResourceParameters<TResource> | Represents operation parameters for resource TResource. Default to KeysOf<T>. |
|
||||
| ResourceCollectionParameters<TResource> | Represents collection operation parameters for resource TResource. Default to ParentKeysOf<T> |
|
||||
| ResourceCreatedResponse<T> | Resource create operation completed successfully. |
|
||||
| ResourceDeletedResponse | Resource deleted successfully. |
|
||||
|
||||
## Decorators
|
||||
|
||||
The `@cadl-lang/rest` library defines the following decorators:
|
||||
- ### HTTP namespace
|
||||
|
||||
### `@parentResource`
|
||||
The `@cadl-lang/rest` library defines the following decorators in `Cadl.Http` namespace:
|
||||
|
||||
Syntax:
|
||||
| Declarator | Scope | Usage |
|
||||
| ----------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| @get | operations | indicating operation uses HTTP `GET` verb. |
|
||||
| @put | operations | indicating operation uses HTTP `PUT` verb. |
|
||||
| @post | operations | indicating operation uses HTTP `POST` verb. |
|
||||
| @patch | operations | indicating operation uses HTTP `PATCH` verb. |
|
||||
| @delete | operations | indicating operation uses HTTP `DEL` verb. |
|
||||
| @head | operations | indicating operation uses HTTP `HEAD` verb. |
|
||||
| @header | model properties and operation parameters | indicating the properties are request or response headers. |
|
||||
| @query | model properties and operation parameters | indicating the properties are in the request query string. |
|
||||
| @body | model properties and operation parameters | indicating the property is in request or response body. Only one allowed per model and operation. |
|
||||
| @path | model properties and operation parameters | indicating the properties are in request path. |
|
||||
| @statusCode | model properties and operation parameters | indicating the property is the return status code. Only one allowed per model. |
|
||||
| @server | namespace | Configure the server url for the service. |
|
||||
|
||||
- ### REST namespace
|
||||
|
||||
The `@cadl-lang/rest` library defines the following decorators in `Cadl.Rest` namespace:
|
||||
|
||||
| Declarator | Scope | Syntax |
|
||||
| ------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| @produces | namespace, operations | Syntax:<br> `@produces(mimetypeString)` <br><br>Note:<br> The `@produces` decorator is used to specify the MIME media types or representations a resource can produce and send back to the client. |
|
||||
| @consumes | namespace, operations | Syntax:<br> `@consumes(mimetypeString)` <br><br>Note:<br> The `@consumes` decorator is used to specify which MIME media types of representations a resource can accept, or consume, from the client. |
|
||||
| @discriminator | models | Syntax:<br> `@discriminator(kindString)` <br><br>Note:<br> `@discriminator` allows defining polymorphic models to be used by API as parameters and return types. In many strongly typed languages, they are expressed as inheritance. |
|
||||
| @readsResource | operations | Syntax:<br> `@readsResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Read operation for a particular resource. |
|
||||
| @createsResource | operations | Syntax:<br> `@createsResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Create operation for a particular resource. |
|
||||
| @createsOrUpdatesResource | operations | Syntax:<br> `@createsOrUpdatesResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the CreatesOrUpdate operation for a particular resource. |
|
||||
| @updatesResource | operations | Syntax:<br> `@updatesResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Update operation for a particular resource. |
|
||||
| @deletesResource | operations | Syntax:<br> `@deletesResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the Delete operation for a particular resource. |
|
||||
| @listsResource | operations | Syntax:<br> `@listsResource(modelType)` <br><br>Note:<br> This decorator is to used to signal the operation that is the List operation for a particular resource. |
|
||||
| @parentResource | models | Syntax:<br> `@parentResource(parentModelTypeReference)` <br><br>Note:<br> `@parentResource` marks a model property with a reference to its parent resource type. The first argument should be a reference to a model type which will be treated as the parent type of the target model type. This will cause the `@key` properties of all parent types of the target type to show up in operations of the `Resource*<T>` interfaces defined in this library. |
|
||||
| @segment | model properties, operation parameters | Syntax:<br> `@segment(segmentString)` <br><br>Note:<br>`@segment` defines the preceding path segment for a `@path` parameter in auto-generated routes. The first argument should be a string that will be inserted into the operation route before the path parameter's name field. For exmaple: <br> `op getUser(@path @segment("users") userId: string): User` <br> will produce the route `/users/{userId}`. |
|
||||
| @segmentOf | models | Syntax:<br> `@segment(segmentString)` <br><br>Note:<br>`@segmentOf` returns the URL segment of a given model if it has `@segment` and `@key` decorator. |
|
||||
| @segmentSeparator | model properties, operation parameters, or operations | Syntax:<br> `@segmentSeparator(separatorString)` <br><br>Note:<br> `@segmentSeparator` defines the separator string that is inserted between the target's `@segment` and the preceding route path in auto-generated routes. <br> The first argument should be a string that will be inserted into the operation route before the target's `@segment` value. Can be a string of any length. Defaults to `/`. |
|
||||
| @route | operations, namespaces, interfaces | Syntax:<br> `@route(routeString)` <br><br>Note:<br> `@route` defines the relative route URI for the target operation The first argument should be a URI fragment that may contain one or more path parameter fields.If the namespace or interface that contains the operation is also marked with a `@route` decorator, it will be used as a prefix to the route URI of the operation. |
|
||||
| @autoRoute | operations | Syntax:<br> `@autoRoute()` <br><br>Note:<br>`@autoRoute` enables automatic route generation for an operation, namespace, or interface. <br> When applied to an operation, it automatically generates the operation's route based on path parameter metadata. When applied to a namespace or interface, it causes all operations under that scope to have auto-generated routes. |
|
||||
|
||||
## Interfaces
|
||||
|
||||
- ### HTTP namespace
|
||||
None
|
||||
- ### REST namespace
|
||||
|
||||
These standard interfaces defines resource operations in basic building blocks that you can expose on the resources. You can use `extends` to compose the operations to meet the exact needs of your resource APIs.
|
||||
|
||||
For example, for below `foo` model
|
||||
|
||||
```
|
||||
@parentResource(parentModelTypeReference)
|
||||
model foo {
|
||||
@key id: string;
|
||||
name: string;
|
||||
}
|
||||
```
|
||||
|
||||
`@parentResource` marks a model property with a reference to its parent resource type
|
||||
- `foo` resource supports full CRUDL operations.
|
||||
|
||||
The first argument should be a reference to a model type which will be treated as the parent
|
||||
type of the target model type. This will cause the `@key` properties of all parent types of
|
||||
the target type to show up in operations of the `Resource*<T>` interfaces defined in this library.
|
||||
|
||||
`@parentResource` can only be applied to models.
|
||||
|
||||
### `@segment`
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
@segment(segmentString)
|
||||
```Cadl
|
||||
interface FooService extends Resource.ResourceOperations<Foo, Error>;
|
||||
```
|
||||
|
||||
`@segment` defines the preceding path segment for a `@path` parameter in auto-generated routes
|
||||
- `foo` resource supports only CRD operations.
|
||||
|
||||
The first argument should be a string that will be inserted into the operation route before the
|
||||
path parameter's name field. For example:
|
||||
|
||||
```
|
||||
op getUser(
|
||||
@path
|
||||
@segment("users")
|
||||
userId: string
|
||||
): User
|
||||
```Cadl
|
||||
interface WidgetService
|
||||
extends Resource.ResourceRead<Widget, Error>,
|
||||
Resource.ResourceCreate<Widget, Error>,
|
||||
Resource.ResourceDelete<Widget, Error> {
|
||||
}
|
||||
```
|
||||
|
||||
Would produce the route `/users/{userId}`.
|
||||
-
|
||||
|
||||
`@segment` can only be applied to model properties or operation parameters.
|
||||
|
||||
### `@route`
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
@route(routeString)
|
||||
```
|
||||
|
||||
`@route` defines the relative route URI for the target operation
|
||||
|
||||
The first argument should be a URI fragment that may contain one or more path parameter fields.
|
||||
If the namespace or interface that contains the operation is also marked with a `@route` decorator,
|
||||
it will be used as a prefix to the route URI of the operation.
|
||||
|
||||
`@route` can only be applied to operations, namespaces, and interfaces.
|
||||
|
||||
### `@autoRoute`
|
||||
|
||||
Syntax:
|
||||
|
||||
```
|
||||
@autoRoute()
|
||||
```
|
||||
|
||||
`@autoRoute` enables automatic route generation for an operation, namespace, or interface.
|
||||
|
||||
When applied to an operation, it automatically generates the operation's route based on path parameter
|
||||
metadata. When applied to a namespace or interface, it causes all operations under that scope to have
|
||||
auto-generated routes.
|
||||
| Interfaces | Notes |
|
||||
| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
|
||||
| ResourceRead<TResource, TError> | Resource GET operation |
|
||||
| ResourceCreateOrUpdate<TResource, TError> | Resource PUT operation |
|
||||
| ResourceCreate<TResource, TError> | Resource POST operation |
|
||||
| ResourceUpdate<TResource, TError> | Resource PATCH operation |
|
||||
| ResourceDelete<TResource, TError> | Resource DEL operation |
|
||||
| ResourceList<TResource, TError> | Resource LIST operation which is a GET operation from a parent resource. |
|
||||
| ResourceInstanceOperations<TResource, TError> | Combines resource GET + PATCH + DEL operations |
|
||||
| ResourceCollectionOperations<TResource, TError> | Combines resource POST + LIST operations |
|
||||
| ResourceOperations<TResource, TError> | Combines resource instance and collection operations. Includes GET + PATCH + DEL + POST + LIST |
|
||||
| SingletonResourceRead<TSingleton, TResource, TError> | Singleton resource GET operation. |
|
||||
| SingletonResourceUpdate<TSingleton, TResource, TError> | Singleton resource PATCH operation. |
|
||||
| SingletonResourceOperations<TSingleton, TResource, TError> | Combines resource GET + PATCH operations |
|
||||
| ExtensionResourceRead<TExtension, TResource, TError> | Extension resource GET operation. |
|
||||
| ExtensionResourceCreateOrUpdate<TExtension, TResource, TError> | Extension resource PUT operation |
|
||||
| ExtensionResourceCreate<TExtension, TResource, TError> | Extension resource POST operation |
|
||||
| ExtensionResourceUpdate<TExtension, TResource, TError> | Extension resource PATCH operation |
|
||||
| ExtensionResourceDelete<TExtension, TResource, TError> | Extension resource GET operation |
|
||||
| ExtensionResourceList<TExtension, TResource, TError> | Extension resource LIST operation which is a GET operation from a parent resource. |
|
||||
| ExtensionResourceInstanceOperations<TExtension, TResource, TError> | Combines extension resource GET + PATCH + DEL operations. |
|
||||
| ExtensionResourceCollectionOperations<TExtension, TResource, TError> | Combines extension resource POST + LIST operations. |
|
||||
| ExtensionResourceOperations<TExtension, TResource, TError> | Combines extension resource instance and collection operations. Includes GET + PATCH + DEL + POST + LIST operations. |
|
||||
|
||||
## See also
|
||||
|
||||
- [HTTP example](https://cadlplayground.z22.web.core.windows.net/?c=aW1wb3J0ICJAY2FkbC1sYW5nL3Jlc3QiOwoKQHNlcnZpY2VUaXRsZSgiV2lkZ2V0IFPGFSIpCm5hbWVzcGFjZSBEZW1vxxg7CnVzaW5nIENhZGwuSHR0cDsKCm1vZGVsIMdAewogIEBrZXkgaWQ6IHN0cmluZzsKICB3ZWlnaHQ6IGludDMyxBFjb2xvcjogInJlZCIgfCAiYmx1ZSI7Cn0KCkBlcnJvcsdWRcQMxVVjb2Rly0BtZXNzYWdlymR9CgppbnRlcmbkALLmAI3nALTFP0DkAJ1saXN0KCk6xx9bXSB8xmHEUUByb3V0ZSgid8Uccy97aWR9IinGOHJlYWQoQHBhdGjrANfJSM1GcG9zdCBjcmVhdGUoQGJvZHkgxAXIK9Y0x3pjdXN0b21HZXTId8kR6gC0yjh9Cg%3D%3D):
|
||||
- [REST example](https://cadlplayground.z22.web.core.windows.net/?c=aW1wb3J0ICJAY2FkbC1sYW5nL3Jlc3QiOwoKQHNlcnZpY2VUaXRsZSgiV2lkZ2V0IFPGFSIpCm5hbWVzcGFjZSBEZW1vxxg7Cgp1c2luZyBDYWRsLkh0dHA7zBFSZXN0OwoKbW9kZWwgx1J7CiAgQGtleSBpZDogc3RyaW5nOwogIHdlaWdodDogaW50MzLEEWNvbG9yOiAicmVkIiB8ICJibHVlIjsKfQoKQGVycm9yx1ZFxAzFVWNvZGXLQG1lc3NhZ2XKZH0KCmludGVyZuQAxOYAjecAxiBleHRlbmRzIFJlc291cmNl5AC5xQlPcGVyYXRpb25zPMYyLMZxPsVyQOQA0EByb3V0ZSgiY3VzdG9tR2V0IikgyQwoKTrHa%2BQAgA%3D%3D):
|
||||
- [Cadl Getting Started](https://github.com/microsoft/cadl#getting-started)
|
||||
- [Cadl Tutorial](https://github.com/microsoft/cadl/blob/main/docs/tutorial.md)
|
||||
|
||||
```
|
||||
|
||||
```
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче